Troubleshooting
A complete guide to diagnosing and resolving errors in the StoryFlow Unreal Engine plugin. Covers every runtime error message, debugging techniques, and common solutions.
Error Handling Overview
The StoryFlow plugin reports errors through two channels:
OnError Delegate
A BlueprintAssignable delegate on UStoryFlowComponent. Bind to this in Blueprint or C++ to handle errors in your game — for example, showing a message to the player or logging to your own system.
Output Log
All errors are also logged via UE_LOG(LogStoryFlow, Error, ...). Open the Output Log panel in the Unreal Editor and filter by "StoryFlow" to see all plugin messages.
Errors Are Non-Fatal
StoryFlow errors do not crash your game. When an error occurs, the runtime stops processing the current node chain and fires OnError. 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, bind to the OnError delegate on your UStoryFlowComponent.
C++ Example
// In your actor's BeginPlay or initialization
UStoryFlowComponent* StoryFlow = FindComponentByClass<UStoryFlowComponent>();
if (StoryFlow)
{
StoryFlow->OnError.AddDynamic(this, &AMyActor::HandleStoryFlowError);
}
// Handler function
void AMyActor::HandleStoryFlowError(const FString& ErrorMessage)
{
UE_LOG(LogTemp, Warning, TEXT("StoryFlow error: %s"), *ErrorMessage);
// Show error in your UI, log to analytics, etc.
}Blueprint
In your actor's Blueprint, select the StoryFlowComponent and add an event binding for On Error in the Details panel under StoryFlow | Events. The event provides a single ErrorMessage string parameter.
Initialization Errors
These errors occur when calling StartDialogue() or StartDialogueWithScript() before the component is properly configured.
| Error Message | Cause | Solution |
|---|---|---|
No script configured for StoryFlowComponent | Called StartDialogue() without setting the Script property. | Set the Script property in the Details panel or use StartDialogueWithScript() instead. |
StartDialogueWithScript called with empty ScriptPath | Passed an empty string to StartDialogueWithScript(). | Provide a valid script path (e.g., "Content/main.sfe"). |
StoryFlow Subsystem not available | The UStoryFlowSubsystem hasn't initialized. This can happen if called too early in the game lifecycle. | Ensure you call StartDialogue() after BeginPlay. The subsystem initializes with the game instance. |
No StoryFlow project loaded | No project asset exists at the default path and none was set manually. | Import your StoryFlow project via the importer or call SetProject() on the subsystem. |
Script not found: {path} | The Script property references a script path that doesn't exist in the imported project. | Check the script path matches one of the imported scripts. The Output Log lists all available scripts when this error occurs. |
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 Unreal. 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. 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. |
Start node not found in script: {path} | The target script called by a runScript node is missing a Start node. | Ensure the target script has a Start node. Re-export from StoryFlow Editor. |
Max script nesting depth exceeded ({depth}) | Scripts calling other scripts have exceeded the maximum nesting depth. 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. | 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
| 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 |
Debugging Strategies
Filter the Output Log
All StoryFlow plugin messages use the LogStoryFlow log category. In the Output Log panel, type "StoryFlow" into the search box to filter out unrelated engine messages. This makes it much easier to see errors, warnings, and informational messages from the plugin.
Track Variable Changes
Bind to the OnVariableChanged delegate 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.
StoryFlow->OnVariableChanged.AddDynamic(this, &AMyActor::OnVarChanged);
void AMyActor::OnVarChanged(const FString& Id, FStoryFlowVariant Value, bool bGlobal)
{
UE_LOG(LogTemp, Log, TEXT("Variable '%s' changed (global=%s)"),
*Id, bGlobal ? TEXT("true") : TEXT("false"));
}Use Live Sync for Rapid Iteration
When debugging, use Live Sync to push changes from StoryFlow Editor to Unreal without restarting PIE. 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 Unreal, 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 Unreal plugin.