Troubleshooting
A complete guide to diagnosing and resolving errors in the StoryFlow Godot plugin. Covers every runtime error message, debugging techniques, and common solutions.
Error Handling Overview
The StoryFlow plugin reports errors through two channels:
error_occurred Signal
A signal on StoryFlowComponent. Connect to this in GDScript to handle errors in your game - for example, showing a message to the player or logging to your own system.
Output Panel
All errors are also logged via push_warning() and push_error(). Open the Output panel in the Godot Editor to see all plugin messages alongside your own prints.
Errors Are Non-Fatal
StoryFlow errors do not crash your game. When an error occurs, the runtime stops processing the current node chain and emits error_occurred. Dialogue execution may end or stall, but your game continues running. This lets you handle errors gracefully in your UI.
Listening for Errors
To respond to errors at runtime, connect to the error_occurred signal on your StoryFlowComponent.
# In your scene script's _ready()
func _ready() -> void:
var story_flow = $StoryFlowComponent
story_flow.error_occurred.connect(_on_storyflow_error)
# Handler function
func _on_storyflow_error(error_message: String) -> void:
push_warning("StoryFlow error: " + error_message)
# Show error in your UI, log to analytics, etc.
# Optionally stop dialogue to prevent broken UI state
if story_flow.is_dialogue_active():
story_flow.stop_dialogue()
You can also connect the signal in the Godot Editor via the Node panel's Signals tab. Select the StoryFlowComponent node, find error_occurred(message: String), and connect it to a handler method on your script.
Initialization Errors
These errors occur when calling start_dialogue() or start_dialogue_with_script() before the component is properly configured.
| Error Message | Cause | Solution |
|---|---|---|
No script configured for StoryFlowComponent | Called start_dialogue() without setting the script_path property. | Set the script_path property in the Inspector panel or use start_dialogue_with_script() instead. |
start_dialogue_with_script called with empty path | Passed an empty string to start_dialogue_with_script(). | Provide a valid script path (e.g., "scripts/main"). |
StoryFlowRuntime autoload not found | The StoryFlowRuntime autoload hasn't initialized. This can happen if the plugin is not enabled or called too early in the lifecycle. | Ensure the plugin is enabled in Project > Project Settings > Plugins. Call start_dialogue() after _ready(). |
No StoryFlow project loaded. Import a project or set it via StoryFlowRuntime. | No project has been imported or set on the manager. | Import your StoryFlow project via the importer or call set_project() on the manager. |
Script not found: {path} | The script_path property references a script path that doesn't exist in the imported project. | Check the script path matches one of the imported scripts. Use get_manager().get_all_script_paths() to list available scripts. |
Start node (id=0) not found in script | The script data doesn't contain a Start node with id "0". The script may be corrupted or was exported incorrectly. | Re-export the project from StoryFlow Editor and re-import into Godot. Verify the script has a Start node in the editor. |
Graph Execution Errors
These errors occur during node graph traversal when the runtime encounters invalid connections or structural problems.
| Error Message | Cause | Solution |
|---|---|---|
Target node not found: {id} | An edge references a node ID that doesn't exist in the script. The target node may have been deleted after the connection was created. | Open the script in StoryFlow Editor and fix any broken connections. Re-export and re-import the project. |
Max processing depth exceeded ({depth}) - possible cyclic graph | The node processing loop has exceeded the safety limit (1000). This happens when non-dialogue nodes form a cycle with no exit condition. | Check for loops in your non-dialogue node chains. Make sure every loop has a Branch node that eventually exits the cycle. |
Script & Flow Errors
These errors occur when using runScript or runFlow nodes to call other scripts or flows.
| Error Message | Cause | Solution |
|---|---|---|
RunScript node has no script path | A runScript node has no script path configured. | Open the script in StoryFlow Editor and set a valid script path on the Run Script node. |
Max script nesting depth exceeded ({depth}) | Scripts calling other scripts have exceeded the maximum nesting depth (20). This usually indicates a circular dependency. | Check your Run Script nodes for circular references. Reorganize your script hierarchy to avoid loops. |
RunFlow node has no flow ID | A runFlow node has no flow selected. | Open the script in StoryFlow Editor and configure the Run Flow node with a valid flow. |
Too many nested flows - possible infinite loop | Flows calling other flows have exceeded the maximum nesting depth (50). | Check your Run Flow nodes for circular references. Make sure flows don't call themselves or form a loop. |
EntryFlow not found for flowId: {id} | A Run Flow node references a flow that doesn't exist in the script. | Verify the flow exists in the script. The flow may have been renamed or deleted in the editor. |
Depth Limits
The plugin enforces depth limits at multiple levels to prevent infinite recursion from freezing your game.
| Resource | Maximum Depth | Description |
|---|---|---|
| Script nesting | 20 | Maximum runScript calls deep before the runtime stops |
| Flow nesting | 50 | Maximum runFlow calls deep before the runtime stops |
| Evaluation depth | 100 | Maximum node evaluation chain depth (nested boolean/conversion logic) |
| Processing depth | 1000 | Maximum consecutive non-dialogue nodes processed before the runtime stops |
Debugging Strategies
Check the Output Panel
All StoryFlow plugin messages are printed to Godot's Output panel via push_warning() and push_error(). When something goes wrong, the Output panel is the first place to look. Error messages include the specific node ID or script path involved, making it easy to pinpoint the source of the problem.
Track Variable Changes
Connect to the variable_changed signal to monitor variable state during execution. This is especially useful for debugging Branch nodes that always take the same path - you can verify the boolean variable has the expected value at the moment the Branch node evaluates.
func _ready() -> void:
story_flow_component.variable_changed.connect(_on_variable_changed)
func _on_variable_changed(info: StoryFlowVariableChangeInfo) -> void:
print("Variable '%s' (id: %s) changed to '%s' (global: %s)" % [
info.name,
info.id,
info.value.to_display_string(),
str(info.is_global)
])Use Live Sync for Rapid Iteration
When debugging, use Live Sync to push changes from StoryFlow Editor to Godot without re-importing manually. This lets you fix a broken connection in the editor and immediately test the fix in-game.
Cross-Reference with the Editor
Many plugin errors mirror editor runtime errors. If you see an error in Godot, try playing the same script in StoryFlow Editor's Play Window to reproduce it. The editor's Runtime Debugger provides a visual, step-by-step view of execution that can pinpoint the exact node causing the problem.
Editor Errors Page
For a complete list of editor-side error messages and their solutions, see the Errors & Troubleshooting page in the editor documentation. Many errors are shared between the editor runtime and the Godot plugin.