# Pitfalls Level: Intermediate ## Goal Use this page as a quick symptom-first checklist when a graph does not behave the way the authored graph suggests. Start here when you need fast orientation. After the first likely cause is identified, move to the related page for the deeper workflow. ## How to Use This Page 1. Find the symptom group closest to what you see in Unity. 2. Run the first check before changing the graph. 3. Apply the smallest fix that matches the cause. 4. Use the Related link when the issue needs a full debugging workflow. ## Graph Does Not Start | Symptom | Likely cause | First check | Fix | Related | | ----------------------------------------------- | ----------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | | Nothing happens in Play Mode. | The scene object is not running the graph you edited. | Select the GameObject that should own the behavior and inspect `FlowCoreProcess`. | Assign the correct graph asset, enable the process, and test again. | [Debug a Running Graph](/flow-core-docs/documentation/how-to-guides/debug-a-running-graph.md) | | A Unity `Start` Trigger never fires. | Trigger settings or scene owner mismatch. | Confirm `Trigger Bus Type = Unity` and `Unity Event = Start` on the graph assigned to that scene object. | Use the intended Unity event and verify the same object owns the process. | [Graph Debugging](/flow-core-docs/documentation/troubleshooting/graph-debugging.md) | | An Entry call fails after rename. | The caller still uses the old Entry title. | Compare the Enter node title with the external call name. | Update the caller or restore the Entry title. | [Lifecycle and Dataflow](/flow-core-docs/documentation/runtime-guide/lifecycle-and-dataflow.md) | | The graph starts on one object but not another. | Shared graph asset with different scene bindings. | Set Debug Context to each object and compare `FlowCoreProcess` bindings. | Bind the same required graph, Local Blackboards, and start settings on each instance. | [Debug Context](/flow-core-docs/documentation/editor-guide/debug-context.md) | ## Wrong or Missing Data | Symptom | Likely cause | First check | Fix | Related | | --------------------------------------------- | ------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | | A value reads as null, empty, or default. | Blackboard scope, index, key, or type mismatch. | Check the value source in the node or instruction. | Match scope, index, key spelling, and value type exactly. | [Blackboard UI](/flow-core-docs/documentation/editor-guide/blackboard-ui.md) | | The beginner Hello graph logs the wrong text. | The `Log String` instruction reads a different Blackboard value than expected. | Confirm Local index `0`, key `Say`, and a `String` value on the bound Blackboard. | Add the Blackboard to `Local Blackboards` or correct the instruction value path. | [First 15 Minutes](/flow-core-docs/documentation/tutorials/first-15-minutes.md) | | Scene data changes unexpectedly. | The graph relies on implicit Scene Blackboard selection. | Check whether more than one Scene Blackboard exists. | Bind the intended Scene Blackboard explicitly when deterministic ownership matters. | [Performance and Failure Modes](/flow-core-docs/documentation/troubleshooting/performance-and-failure-modes.md) | | List changes appear to do nothing. | Index rules, empty list, or disabled index normalization. | Check the list size and whether Normalize Element Index or Normalize Index is enabled. | Use a non-negative index, or enable normalization when negative indices should wrap. | [Performance and Failure Modes](/flow-core-docs/documentation/troubleshooting/performance-and-failure-modes.md) | | Runtime edits disappear. | A runtime-only or non-persistent value was changed during Play Mode. | Check whether the value type supports Unity or Flow Core persistence. | Treat runtime-only values as temporary, or use a persistent/custom type when the data must survive. | [Persistence](/flow-core-docs/documentation/api-extension-guide/persistence.md) | ## Chain Stops Early | Symptom | Likely cause | First check | Fix | Related | | ---------------------------------------------------- | --------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- | | The start node fires but the next Action never runs. | Missing connection, rejected Guard, or disabled pass gate. | Follow the connection from the start node to the next node and inspect Guard state. | Connect the branch, fix the Guard, or re-enable the pass gate. | [Graph Debugging](/flow-core-docs/documentation/troubleshooting/graph-debugging.md) | | A branch ends quietly. | `Reject Result` or busy behavior returns Invalid. | Inspect Guard `Reject Result` and node Invoke Mode. | Use Invalid for optional fallthrough and Abort when the rejection should be visible. | [Invoke and Reject Modes](/flow-core-docs/documentation/reference/invoke-and-reject-modes.md) | | A repeated event appears ignored. | The node is busy and Invoke Mode skips, aborts, or queues later work. | Check whether the node is still running when the next event arrives. | Choose Queue for required ordered work, or Bypass/Invalid for repeated non-critical updates. | [Invoke and Reject Modes](/flow-core-docs/documentation/reference/invoke-and-reject-modes.md) | | A control input cancels more than expected. | Multiple active chains match the same root or current node. | Identify the chain root and current executing node. | Use separate roots, clearer Start New Chain boundaries, or narrower control routing. | [Invoke and Reject Modes](/flow-core-docs/documentation/reference/invoke-and-reject-modes.md) | ## Editor Preview Confusion | Symptom | Likely cause | First check | Fix | Related | | --------------------------------------- | ------------------------------------------------------------- | -------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | | Summaries show unresolved Local values. | Debug Context is missing or points to the wrong object. | Look at the Graph Editor Debug Context field. | Set Debug Context to the GameObject with the running `FlowCoreProcess`. | [Debug Context](/flow-core-docs/documentation/editor-guide/debug-context.md) | | Editor previews do not match Play Mode. | The graph asset is shared by multiple process instances. | Compare the selected Debug Context with the object that produced the runtime behavior. | Switch Debug Context before inspecting each instance. | [Debug Context](/flow-core-docs/documentation/editor-guide/debug-context.md) | | Visual debugging looks empty. | The selected process is not the one that ran. | Confirm the runtime owner and Debug Context are the same object. | Select the process that received the Trigger or Entry call. | [Graph Debugging](/flow-core-docs/documentation/troubleshooting/graph-debugging.md) | | Play Mode editing is locked. | Flow Core settings prevent editing graph assets in Play Mode. | Check the Play Mode editing lock setting. | Change the setting only when the team intentionally wants Play Mode graph edits. | [FlowCore Settings](/flow-core-docs/documentation/reference/flow-core-settings.md) | ## Subgraph and Lifecycle Issues | Symptom | Likely cause | First check | Fix | Related | | -------------------------------------------------------- | --------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | | Subgraph Triggers do not fire. | The subgraph activation window is not active. | Confirm the parent SubFlowGraph is currently running when the Trigger should listen. | Start the subgraph before expecting its internal Triggers to receive events. | [Lifecycle and Dataflow](/flow-core-docs/documentation/runtime-guide/lifecycle-and-dataflow.md) | | A lifecycle Trigger runs earlier or later than expected. | Unity event order or scene owner differs from the test object. | Confirm which GameObject owns the `FlowCoreProcess` and which Unity event is selected. | Use a visible log step and test the exact lifecycle event on the owning object. | [Run a Flow Graph in a Scene](/flow-core-docs/documentation/tutorials/run-a-flow-graph-in-a-scene.md) | | A graph works in one scene but not another. | Scene bindings, Scene Blackboard selection, or additive scene setup differ. | Compare process bindings and scene Blackboard ownership between scenes. | Bind required data explicitly and keep scene setup consistent. | [Debug a Running Graph](/flow-core-docs/documentation/how-to-guides/debug-a-running-graph.md) | ## Save and Cache Pitfalls | Symptom | Likely cause | First check | Fix | Related | | ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | | Save loads back into broken combat or dialogue logic. | `Persist Local Process` restores a coarse runtime boundary, not an exact instruction breakpoint. | Check whether save/load happens during combat, rapid dialogue branching, or dense Trigger activity. | Save only in stable windows such as hubs, camps, bases, or after major logic handoff. | [Persistence](/flow-core-docs/documentation/api-extension-guide/persistence.md) | | Replace or Append does not change scene values immediately. | The operation mutates cached Blackboard data, not live Blackboard objects. | Check whether you changed cache data or applied a load/import path to live objects. | Use Replace/Append as cache preparation, then run the normal apply/load path when live values must change. | [Persistence](/flow-core-docs/documentation/api-extension-guide/persistence.md) | | Clear removed the wrong cache entries. | `MatchedOnly` and `ExceptMatched` were swapped. | Recheck the GUID list and match mode before clearing. | Export first when safety matters, then clear only the intended subset. | [Blackboard UI](/flow-core-docs/documentation/editor-guide/blackboard-ui.md) | | Exported package is not the latest runtime state. | The runtime cache was not refreshed after live Blackboard changes. | Confirm whether cache preparation ran before export. | Refresh/cache runtime state first, then export the subset. | [Persistence](/flow-core-docs/documentation/api-extension-guide/persistence.md) | | A load duplicates additive scene content. | Save restore and startup logic both load the same additive scene. | Check `Reload Saved Additional Scenes` and startup scene-loading logic. | Let either the save file or startup logic own additive scene loading, not both. | [Persistence](/flow-core-docs/documentation/api-extension-guide/persistence.md) | ## Performance and Timing Pitfalls | Symptom | Likely cause | First check | Fix | Related | | ------------------------------------- | ---------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------- | | Graph feels laggy. | High-frequency Trigger combined with Queue. | Check Trigger frequency and Invoke Mode on nodes reached by repeated events. | Reduce frequency, use Bypass for non-critical repeats, or keep Queue only where every request matters. | [Runtime Cost Monitoring](/flow-core-docs/documentation/troubleshooting/runtime-cost-monitoring.md) | | Work bunches up after several events. | Queued chains are waiting behind earlier executions. | Look for async waits, long Action lists, or repeated events entering the same busy node. | Shorten the chain, split phases, or change busy behavior. | [Invoke and Reject Modes](/flow-core-docs/documentation/reference/invoke-and-reject-modes.md) | | Cost rises while the scene is idle. | Timer, service, polling, or repeated Trigger runs too often. | Open runtime cost monitoring for the process that owns the graph. | Lower the update frequency or move expensive work behind Guards. | [Runtime Cost Monitoring](/flow-core-docs/documentation/troubleshooting/runtime-cost-monitoring.md) | | A visually small graph stutters. | A custom instruction, condition, or generated call is expensive. | Profile the chain sample, not just the number of nodes. | Optimize the measured instruction or move expensive work out of hot paths. | [Performance and Failure Modes](/flow-core-docs/documentation/troubleshooting/performance-and-failure-modes.md) | ## Related * [Debug a Running Graph](/flow-core-docs/documentation/how-to-guides/debug-a-running-graph.md) * [Graph Debugging](/flow-core-docs/documentation/troubleshooting/graph-debugging.md) * [Blackboard UI](/flow-core-docs/documentation/editor-guide/blackboard-ui.md) * [Debug Context](/flow-core-docs/documentation/editor-guide/debug-context.md) * [Invoke and Reject Modes](/flow-core-docs/documentation/reference/invoke-and-reject-modes.md) * [Persistence](/flow-core-docs/documentation/api-extension-guide/persistence.md) * [Runtime Cost Monitoring](/flow-core-docs/documentation/troubleshooting/runtime-cost-monitoring.md) * [Performance and Failure Modes](/flow-core-docs/documentation/troubleshooting/performance-and-failure-modes.md) --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://flow-core.gitbook.io/flow-core-docs/documentation/troubleshooting/pitfalls.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.