> For the complete documentation index, see [llms.txt](https://flow-core.gitbook.io/flow-core-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://flow-core.gitbook.io/flow-core-docs/documentation/how-to-guides/debug-a-running-graph.md). # Debug a Running Graph ## Goal Find the scene object, graph path, Blackboard value, or return result that explains why a graph behaves differently from what you authored. ## When To Use This Use this guide after the graph is already connected to a scene object and something looks wrong in Play Mode. Common examples include a Trigger that never fires, an Action that runs with the wrong value, a Guard that appears to stop the chain, or a graph that works on one GameObject but not another. This page is the practical workflow. For deeper symptom tables, use [Graph Debugging](/flow-core-docs/documentation/troubleshooting/graph-debugging.md) and [Performance and Failure Modes](/flow-core-docs/documentation/troubleshooting/performance-and-failure-modes.md). ## Prerequisites * A scene GameObject has a `FlowCoreProcess`. * The process has the Flow Graph asset assigned. * The graph has a known start point, such as a `Trigger`, `Enter`, or module root. * Required `Blackboard`, `SceneBlackboard`, or `GlobalBlackboard` data exists. ## Steps 1. Start from the visible symptom. Decide what you expected to see before inspecting the graph. Examples: "Console should print `Hello Flow Core`", "the Attack branch should run", or "the door should open when the player interacts." A clear expected result keeps debugging focused. 2. Identify the runtime owner. In the scene Hierarchy, select the GameObject that should own the behavior. Confirm it has the `FlowCoreProcess` that should run the graph. If the same graph asset is assigned to multiple GameObjects, inspect the instance that produced the symptom, not just any object using the same asset. 3. Confirm the graph binding. In the `FlowCoreProcess` Inspector, check that the expected Flow Graph asset is assigned. If the process uses an embedded graph or a graph wrapper, confirm it points to the graph you are editing. A correct graph in the editor does not matter if the scene object is running a different graph. 4. Confirm Blackboard bindings. Check `Local Blackboards` first. A Local read such as `Local[0].Say` only works if the expected `Blackboard` is in that process list at index `0`. Then check Scene and Global data if the node uses those scopes. When more than one Scene Blackboard exists, bind the intended one explicitly. 5. Set Debug Context. Open the Flow Graph editor and set **Debug Context** to the GameObject with the `FlowCoreProcess`. Debug Context does not change runtime behavior. It tells the editor which process instance to use when resolving Local values, scene bindings, summaries, and visual debugging records. 6. Inspect the start point. Select the `Trigger`, `Enter`, `BTRoot`, or module node that should start the behavior. Confirm its settings match the event you are testing. For example, a Unity lifecycle Trigger must be configured for the expected Unity event, and an Entry must use the same name that external code calls. 7. Follow the chain one hop at a time. Trace from the start node through each connected output. Read the selected node summary, its Guard group, and any value fields that come from Blackboard or payload. If a connection is missing, the chain stops there even if later nodes look correct. 8. Compare resolved values with live data. Open the Blackboard UI or select the relevant node value field. Confirm the key spelling, type, scope, and index. A key named `Say` is different from `say`; a String key is different from an Object or reference key; Local scope is different from Scene or Global scope. 9. Read return semantics. If a Guard rejects or a node is busy, check `Reject Result` and `Invoke Mode`. `Abort` usually means the chain stops loudly at that point. `Invalid` means the branch ends as not valid and may allow other branches to continue, depending on the surrounding node. 10. Verify again in Play Mode. Enter Play Mode with the same Debug Context selected. Trigger the behavior once, then watch visual debugging, Console output, Blackboard values, and the visible scene result. Change one suspected cause at a time. ## Expected Result After this workflow, you should know which category the issue belongs to: * The wrong scene object or graph asset is being inspected. * The graph starts from the wrong Trigger, Entry, or module root. * A required connection is missing. * A Blackboard key, type, scope, or index does not match. * A Guard, Invoke Mode, or Reject Result is ending the chain. * The graph is correct, but the visible side effect is failing in another system. ## Troubleshooting | Symptom | Check | Fix | | -------------------------------------------------- | -------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | | Nothing happens in Play Mode. | Graph asset, enabled `FlowCoreProcess`, start Trigger or Entry name. | Assign the correct graph, enable the process, and test the exact start event. | | Editor summaries show unresolved Local data. | Debug Context and `Local Blackboards` list. | Set Debug Context to the process GameObject and add the Blackboard to the expected index. | | A value is present but the node reads the default. | Key spelling, value type, list vs single value, and scope. | Match the node value source to the Blackboard key exactly. | | The graph works on one object but not another. | Shared graph asset with different Local Blackboard data. | Inspect each instance through its own Debug Context. | | The chain stops before the Action. | Guard group, Pass Enabled, Reject Result, and missing connections. | Fix the rejected check or route `Invalid` and `Abort` intentionally. | | BT branch chooses the wrong child. | Child order and composite mode. | Use [BT Debugging](/flow-core-docs/documentation/troubleshooting/bt-debugging.md) for the BT-specific path. | ## Related * [Graph Debugging](/flow-core-docs/documentation/troubleshooting/graph-debugging.md) * [Debug Context](/flow-core-docs/documentation/editor-guide/debug-context.md) * [Blackboard UI](/flow-core-docs/documentation/editor-guide/blackboard-ui.md) * [Invoke and Reject Modes](/flow-core-docs/documentation/reference/invoke-and-reject-modes.md) * [First 15 Minutes](/flow-core-docs/documentation/tutorials/first-15-minutes.md) --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## 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/how-to-guides/debug-a-running-graph.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.