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:

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.

Graph Execution Errors

These errors occur during node graph traversal when the runtime encounters invalid connections or structural problems.

Script & Flow Errors

These errors occur when using runScript or runFlow nodes to call other scripts or flows.

Depth Limits

Forward Compatibility Warnings

When the StoryFlow Editor introduces a new node type that an older runtime version does not understand, the runtime emits a warning and continues execution gracefully. These messages are logged at Warning level through LogStoryFlow. They do not invoke the OnError delegate and they do not crash the game. The intent is to keep older plugin builds usable against newer exported projects while the user upgrades the plugin.

If you see either warning in the Output Log, the most likely cause is that your StoryFlow Editor export uses a node introduced in a newer version of the project format than your installed plugin supports. Update the plugin to the matching version, or remove the unsupported node from the script in the StoryFlow Editor and re-export.

A concrete example: the map operation nodes (getMap, setMap, getMapValue, setMapValue, hasMapKey, mapSize, mapKeys, mapValues, removeMapKey, clearMap, forEachMap) and the modulo and moduloFloat math nodes require plugin 1.2.0 or later. On older plugins they surface as the "Unsupported node type" warnings above. The fix is updating the plugin. The StoryFlow Editor also flags this proactively: when a pre-1.2.0 plugin connects over Live Sync while the open project uses map variables, the editor shows a warning toast during the handshake telling you to update to 1.2.0+.

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 FStoryFlowVariable& Variable, bool bIsGlobal)
{
    UE_LOG(LogTemp, Log, TEXT("Variable '%s' (%s) changed to '%s' (global=%s)"),
        *Variable.Name, *Variable.Id, *Variable.Value.ToString(),
        bIsGlobal ? 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.

Common Issues

Dialogue Works in Editor but Not in Packaged Builds

Dialogue that runs correctly in PIE (Play In Editor) and Simulate mode but produces no output in a packaged build has two distinct causes. Match the symptoms before applying a fix - the remedies do not overlap.

Cause 1: the cooker did not include your StoryFlow assets. By default, the cooker only packages assets that are directly referenced by a map or Blueprint. Since StoryFlow assets are loaded at runtime by the subsystem, the cooker may skip them entirely. The symptom is the whole project going missing in the packaged build: no script resolves, and the runtime typically reports No StoryFlow project loaded because the project asset was cooked out along with everything else.

Fix: Tell the cooker to always include the StoryFlow content directory:

1. Open Project Settings.
2. Navigate to Platforms > Packaging (or search for "Additional Asset Directories to Cook").
3. Under Additional Asset Directories to Cook, add /Game/StoryFlow.
4. Package your project again.

Cause 2: a script or folder name that is invalid in an Unreal package name. Up to plugin version 1.2.1, a script's file name and each folder segment above it went into the package path untouched. Any name containing a character Unreal does not allow in package names - a space, an apostrophe, a dot - produced an asset the loader and cooker can never resolve. The editor and PIE keep working from the in-memory packages, so nothing looks wrong until the game is packaged.

Symptoms that point at this cause rather than at the cooker:

• Only some dialogue is missing. Scripts whose names contain nothing but letters, digits, underscores or hyphens still work in the same packaged build.
• The script's file name, or one of the folder names above it, contains a space, an apostrophe or a dot. That alone is enough. Nothing about the script's content matters.
• On 1.2.2 and later, the sync log carries a warning naming the offending script and the path it imported as.
• On 1.2.1 and earlier, the sync log carries Ensure condition failed: ConvertedToPath. A name containing a dot could also hard-crash the editor inside the asset registry during import.

Fix:

1. Update the plugin to 1.2.2 or later. It sanitizes the script name and every folder segment above it, so the packages it creates are always resolvable.
2. Delete the assets the broken sync produced - the Content/StoryFlow folder in a default setup. This step is not optional: 1.2.2 creates the correct assets but does not remove the old unusable ones.
3. Sync again, or re-import the project.

Sync Cannot Write an Asset

From v1.2.2, a .uasset that cannot be written is reported by name and skipped while the rest of the import continues, and its import hash is not recorded, so the next sync retries that asset instead of skipping it. On earlier versions a single unwritable file took the whole editor down. These messages are logged through LogStoryFlow and do not invoke the runtime's OnError delegate.