> 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/troubleshooting/graph-debugging.md).

# Graph Debugging

Level: Intermediate

## Goal

Find why a graph chain does not start, stops early, runs too often, reads the wrong data, or behaves differently from the graph you authored.

## Symptoms

| Symptom                                   | First place to look                                                  |
| ----------------------------------------- | -------------------------------------------------------------------- |
| Nothing happens in Play Mode.             | Trigger, Entry, graph assignment, or disabled process.               |
| The graph starts but stops early.         | Guard Reject Result, Invoke Mode, disabled node, or missing branch.  |
| The wrong value is used.                  | Blackboard scope, index, key, or Debug Context mismatch.             |
| The chain runs too often.                 | Trigger frequency, duplicate triggers, or repeated event publishing. |
| Visual Debugging shows no records.        | Wrong Debug Context or a different process ran.                      |
| Editor summaries are empty or unresolved. | Debug Context and Blackboard bindings.                               |

## Likely Causes

* The `FlowCoreProcess` has no graph assigned.
* A code call uses an Entry title that does not exist.
* A Trigger is configured for the wrong event source.
* A Local Blackboard is not added to `Local Blackboards`.
* A Blackboard key exists in a different scope or type bucket.
* A Guard rejects the node before it executes.
* Invoke Mode is skipping, delaying, or aborting work while the node is busy.
* Pass Enabled is off on a node with control inputs.
* The editor is previewing the wrong process through Debug Context.

## Checks

1. Confirm the runtime owner.
   * Select the GameObject that should run the graph.
   * Confirm it has `FlowCoreProcess`.
   * Confirm the graph asset or embedded graph is assigned.
2. Confirm the chain start.
   * For a Trigger, verify the event type and source.
   * For an Entry, verify the Entry title or node id used by the caller.
   * For scene lifecycle tests, use a visible result such as `Log String`.
3. Set Debug Context.
   * Open the graph editor.
   * Set Debug Context to the GameObject that owns the process.
   * Keep `Summary` and `Value` visible while checking paths.
4. Validate data paths.
   * Check scope: Local, Scene, or Global.
   * Check Local Blackboard index.
   * Check key spelling and value type.
   * Confirm payload data is available only when the Trigger or Entry provides it.
5. Inspect execution semantics.
   * Check Guard conditions and Reject Result.
   * Check Invoke Mode on nodes that can be reached again while still running.
   * Check Pass Enabled if Enable or Disable control inputs are used.
6. Reproduce in Play Mode.
   * Editor preview can reveal binding mistakes.
   * Play Mode is the source of truth for runtime timing, event order, and visual debugging.

## Fixes

* Assign the graph to `FlowCoreProcess` and enter Play Mode again.
* Rename the Entry or update the caller so both use the same title.
* Bind the required Local Blackboard to the process list.
* Move shared data to the intended Scene or Global scope only when sharing is required.
* Change `Invalid` to `Abort` when a rejected Guard should visibly stop the chain.
* Change `Queue` to `Bypass` or lower Trigger frequency when chains run late.
* Turn Pass Enabled back on if a node should accept incoming chains.
* Set Debug Context to the exact process instance that ran.

## Visual Debugging Notes

* Node color and outline show recent runtime results.
* Moving edge dots show chain direction and timing.
* Pulsing entries usually mean an async wait is still active.
* BT priority scans may not flash every entry, but chain movement still indicates evaluation.
* Visual Debugging records are filtered by process context, so the wrong Debug Context can make a running graph look silent.

## Related

* [Debug Context](/flow-core-docs/documentation/editor-guide/debug-context.md)
* [Detail Level Toggles](/flow-core-docs/documentation/editor-guide/detail-level-toggles.md)
* [Work with Blackboard Data](/flow-core-docs/documentation/how-to-guides/work-with-blackboard-data.md)
* [Invoke and Reject Modes](/flow-core-docs/documentation/reference/invoke-and-reject-modes.md)
* [BT Debugging](/flow-core-docs/documentation/troubleshooting/bt-debugging.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/troubleshooting/graph-debugging.md?ask=<question>
```

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.