Errors & Troubleshooting
A complete reference for every runtime error message in StoryFlow Editor. Each entry explains what the error means, why it happens, and how to fix it.
Understanding Errors
Errors in StoryFlow appear as a red bar at the bottom of the Play Window when you test your project. They occur at runtime (when the story is playing), not while you're editing the node graph. This means an error only surfaces when the runtime reaches the problematic node or connection during execution.
Errors Are Runtime
You won't see errors in the editor canvas. They only appear when you click Play and the runtime encounters something it can't process. Use the Runtime Debugger to step through execution and catch problems early.
If you're using the StoryFlow Unreal Engine plugin, errors are delivered through the OnError delegate and logged to the Output Log. The error messages are similar but not identical — see the plugin troubleshooting page for Unreal-specific errors.
Initialization Errors
These errors occur before your story starts executing, usually during the loading phase.
Electron runtime not available Cause: The Play Window couldn't access Electron's runtime APIs. This usually means the preload bridge failed to load.
Fix: Close the Play Window and try again. If the error persists, restart StoryFlow Editor.
No game data available Cause: The runtime loaded but received no project data. The project file may be empty or corrupted.
Fix: Make sure your project has at least one script file. Check that the .storyflow project file and your .sfe scripts are valid.
No startup script found Cause: No startup script is configured in your project settings, or the configured script doesn't exist in the Content folder.
Fix: Go to Project Settings and set a valid .sfe file as the startup script. Make sure the file exists in your Content folder.
Failed to load embedded data Cause: The Play Window couldn't parse the embedded project data. This can happen if an export or build process produced malformed JSON.
Fix: Try playing again. If the error persists, re-export the project and check that your .sfe files aren't corrupted.
Game runtime not available / Failed to initialize game Cause: The game runtime module failed to initialize. This is a catch-all for unexpected initialization failures.
Fix: Close and reopen the Play Window. If the issue continues, restart StoryFlow Editor. Check the developer console (Ctrl+Shift+I in the Play Window) for more details.
Graph Structure Errors
These errors indicate problems with how nodes are connected in your script graph.
Start node is not connected Cause: The Start node in your script has no outgoing connection. The runtime doesn't know where to begin execution.
Fix: Connect the Start node's output handle to the first node in your story (usually a Dialogue node).
Start node connects to missing node Cause: The Start node has a connection, but the target node it points to doesn't exist. This can happen if you deleted the target node without removing the connection first.
Fix: Delete the broken connection from the Start node and reconnect it to a valid node.
Node not found Cause: The runtime tried to navigate to a node that doesn't exist in the current script. A connection references a node ID that was deleted or never created.
Fix: Open the script in the editor and check for broken connections (edges pointing to nothing). Delete and recreate any broken connections.
Connection not found Cause: The runtime expected an outgoing connection from a node's handle but found none. For example, a Branch node's true or false path has no connection.
Fix: Make sure all required outputs have connections. Branch nodes need both a true and false connection. Dialogue options each need their own outgoing connection.
Invalid node data Cause: A node's internal data is malformed or missing required fields. This is rare and usually indicates a corrupted script file.
Fix: Try deleting the problematic node and recreating it. If the entire script is corrupted, restore from a backup or version control.
Script & Flow Errors
These errors occur when using Run Script or Run Flow nodes to call other scripts or flows.
Script is missing a Start node Cause: A script called via a Run Script node has no Start node. Every script must have exactly one Start node with id "0".
Fix: Open the target script and verify it has a Start node. If it was accidentally deleted, add a new one.
Script's Start node is not connected Cause: A script called via Run Script has a Start node, but it has no outgoing connection.
Fix: Open the target script and connect its Start node to the first node in the flow.
Script not found: {path} Cause: A Run Script node references a script file that doesn't exist. The file may have been renamed, moved, or deleted.
Fix: Check the Run Script node's configured path. Make sure the .sfe file exists in your Content folder. If you renamed or moved the file, update the node's script path.
Only .sfe script files can be run Cause: A Run Script node is trying to execute a file that isn't a .sfe script (e.g., an image or JSON file). This is also a security check to prevent arbitrary file execution.
Fix: Update the Run Script node to point to a valid .sfe file.
RunScript output is not connected Cause: A Run Script node finished executing the target script, but has no outgoing connection to continue the flow in the calling script.
Fix: Connect the Run Script node's output handle to the next node that should execute after the script returns.
Flow "{name}" not found Cause: A Run Flow node references a flow that doesn't exist in the current script. The flow may have been renamed or deleted.
Fix: Check the Run Flow node's configuration and make sure the flow name matches an existing flow in the script.
Dialogue nodes can't be inside ForEach loops Cause: A Dialogue node is placed inside a ForEach loop. Dialogue nodes require player interaction, which conflicts with the synchronous execution model of ForEach loops.
Fix: Move the Dialogue node outside the ForEach loop. If you need to display information from a loop, use variables to collect the data first, then show a Dialogue node after the loop ends.
Depth Limit Errors
StoryFlow enforces depth limits to prevent infinite loops and stack overflows. When the nesting depth exceeds the limit, execution stops with an error.
Too many nested scripts — possible infinite loop Cause: Scripts calling other scripts have exceeded the maximum nesting depth. This usually means Script A calls Script B, which calls Script A again (a circular dependency), or an excessively deep call chain.
Fix: Check your Run Script nodes for circular references. Reorganize your scripts so they don't call each other in loops. Use End nodes to terminate execution before the depth limit is reached.
Too many nested flows — possible infinite loop Cause: Flows calling other flows within the same script have exceeded the maximum nesting depth. A flow may be calling itself directly or indirectly.
Fix: Check your Run Flow nodes for circular references. Make sure flows don't call themselves or form a loop.
| Resource | Maximum Depth | Description |
|---|---|---|
| Script nesting | 20 | Maximum number of scripts calling other scripts via Run Script nodes |
| Flow nesting | 50 | Maximum number of flows calling other flows via Run Flow nodes |
Depth Limits Are Generous
A script depth of 20 or flow depth of 50 is well beyond what most projects need. If you're hitting these limits, it's almost certainly an infinite loop rather than a legitimate deep call chain.
General Errors
Unknown node type: {type} Cause: The runtime encountered a node type it doesn't recognize. This can happen if a script was created with a newer version of StoryFlow Editor that has node types not supported by the current runtime.
Fix: Update StoryFlow Editor to the latest version. If you're running an exported HTML file, re-export it with the current version.
Failed to process game Cause: A general runtime error occurred while processing a node. This is a catch-all for unexpected failures that don't fall into a more specific category.
Fix: Check the developer console (Ctrl+Shift+I in the Play Window) for more detailed error information. The console may show the specific node and data that caused the failure.
Preventing Errors
Most runtime errors can be avoided with good practices during development.
Test Often
Use Play in Editor frequently as you build. Testing after each major change catches errors early before they compound.
Use the Runtime Debugger
The Runtime Debugger shows exactly which nodes execute and in what order. Step through your story to verify connections and variable values.
Connect All Outputs
Make sure every dialogue option, branch path, and script call has a connected output. Disconnected outputs are the most common source of runtime errors.
Avoid Circular Scripts
Plan your script hierarchy so scripts don't call each other in loops. Keep your call chains shallow — most projects work well with 2-3 levels of nesting.
Still Stuck?
If you're encountering an error not listed here or need more help, see the Common Pitfalls section in Best Practices. You can also join our Discord community for help from the team and other users.