Troubleshooting

A complete guide to diagnosing and resolving errors in the StoryFlow Unity plugin. Covers error messages, common pitfalls, and debugging strategies.

Common Errors

The following table lists the most common error messages you may encounter, along with their causes and solutions.

Import Issues

Missing Media Files

If images or audio files referenced in your project are not appearing after import:

• Check the build/media/ directory - The importer reads media files from the build/media/ folder inside the exported project. If files are missing there, re-export from the StoryFlow Editor with media included.
• Verify file formats - Unity imports standard image formats (PNG, JPG) and audio formats (WAV, OGG). MP3 files are supported but WAV is recommended for best compatibility.
• Check the Console - The importer logs warnings for any files it cannot find or import. Look for [StoryFlow] messages.

Newtonsoft.Json Errors

If you see errors related to Newtonsoft.Json or JsonConvert:

• Install the dependency - The StoryFlow package requires com.unity.nuget.newtonsoft-json. This should be installed automatically by the Unity Package Manager when you add StoryFlow. If it was not, install it manually via Window > Package Manager > + > Add package by name and enter com.unity.nuget.newtonsoft-json.
• Version conflicts - If your project already uses a different version of Newtonsoft.Json (e.g., from a third-party asset), you may see version mismatch errors. Ensure only one version is installed.

IL2CPP Stripping Issues

When building for platforms that use IL2CPP (iOS, WebGL, some Android builds), the code stripping process may remove types needed for JSON deserialization at runtime.

Runtime Issues

Variables Not Updating

If variable values do not seem to change when you expect them to:

• Check the scope parameter - The Get/SetXxxVariable methods accept a global parameter. When global is false (default), the method searches local variables first, then global. If you need to target a specific global variable, pass global: true.
• Local variables reset per script - Local variables are scoped to the current script. When execution enters a new script via RunScript, local variables are re-initialized. Global variables persist across all scripts.
• Variable names are case-sensitive - The name parameter must match the variable's display name exactly as defined in the StoryFlow Editor.

// Reading a global variable
bool isQuestComplete = storyFlow.GetBoolVariable("QuestComplete", global: true);

// Reading a local variable (searches local first, then global)
int dialogueCounter = storyFlow.GetIntVariable("counter");

Dialogue Not Starting

If StartDialogue() is called but nothing happens:

• Check for errors - Subscribe to the OnError event to catch initialization errors. The most common cause is a missing project or invalid script path.
• Verify the manager exists - Ensure a StoryFlowManager is in the scene and has been initialized. If using DontDestroyOnLoad, make sure the manager's scene is loaded first.
• Check the script has a Start node - Every script must have a Start node with ID "0". If the script was corrupted or exported incorrectly, re-export from the editor.
• Verify the component is enabled - A disabled component or a disabled GameObject will not process dialogue. Check gameObject.activeInHierarchy and enabled.
• Check the Console - [StoryFlow] prefixed warning and error messages are logged for all failure cases.

Audio Not Playing

If dialogue audio is not playing when expected:

• Check the audio file format - Unity supports WAV, OGG, and MP3. WAV is recommended for best compatibility. Ensure audio files were included in the project export.
• Check the AudioMixerGroup - If DialogueAudioMixerGroup is assigned, ensure the mixer group is not muted and the volume is not set to zero.
• Check the volume multiplier - DialogueVolumeMultiplier defaults to 1.0 but may have been set to 0 in the Inspector.
• Audio requires fresh entry - Audio only plays when the dialogue node is entered for the first time, not when returning to it from a Set* node (which re-renders the dialogue text without replaying audio).
• Check StopAudioOnDialogueEnd - If this is true (default), audio stops when the dialogue ends. If you expect audio to outlast the dialogue, set this to false.

UI Issues

Events Not Firing

If your UI is not receiving dialogue updates:

• Subscribe before starting - Ensure you subscribe to events (e.g., OnDialogueUpdated) before calling StartDialogue(). If you subscribe after the dialogue has already started, you will miss the initial state update.
• Check the DialogueUI field - If you are using a StoryFlowDialogueUI subclass, assign it to the component's DialogueUI field in the Inspector. The binding happens automatically when dialogue starts, but only if the reference is set.
• Manual binding - If you are not using the Inspector field, call dialogueUI.InitializeWithComponent(storyFlowComponent) before starting the dialogue.

// Ensure events are subscribed before starting dialogue
void Start()
{
    var storyFlow = GetComponent<StoryFlowComponent>();

    // Subscribe to events FIRST
    storyFlow.OnDialogueStarted += HandleDialogueStarted;
    storyFlow.OnDialogueUpdated += HandleDialogueUpdated;
    storyFlow.OnDialogueEnded += HandleDialogueEnded;
    storyFlow.OnError += HandleError;

    // THEN start dialogue
    storyFlow.StartDialogue();
}

Options Not Showing

If dialogue options are not appearing in your UI:

• Check IsOnceOnly - Once-only options disappear after being selected. If all options in a dialogue node are once-only and have been used, the options list will be empty. Check state.Options.Count and option.IsSelected.
• Check conditional visibility - Options may be hidden by branch conditions in the StoryFlow Editor. If an option's visibility condition evaluates to false, it will not appear in the Options list.
• Check CanAdvance - If the dialogue state has CanAdvance == true and Options.Count == 0, the dialogue is in "continue" mode (narrative text with no choices). Show a continue button instead of options.

Debugging

Enable Verbose Logging

The plugin includes two logging options in StoryFlowSettings that can help diagnose issues:

• VerboseLogging - Logs every node that is processed during execution. This shows the exact order of node traversal, making it easy to trace the execution path and identify where things go wrong.
• LogVariableChanges - Logs every variable change during execution, including the variable name, new value, and whether it is local or global. Useful for debugging Branch nodes that always take the wrong path.

To enable these options, create a StoryFlowSettings asset via Assets > Create > StoryFlow > Settings, place it in a Resources/ folder, name it StoryFlowSettings, and check the desired logging toggles.

Subscribe to OnError

Always subscribe to the OnError event during development. This catches runtime errors that might otherwise go unnoticed if you are not watching the Console.

var storyFlow = GetComponent<StoryFlowComponent>();

storyFlow.OnError += (message) =>
{
    Debug.LogError($"[StoryFlow Error] {message}");

    // Optionally show in-game error UI during development
    #if UNITY_EDITOR || DEVELOPMENT_BUILD
    ShowDebugOverlay(message);
    #endif
};

Track Variable Changes

Subscribe to OnVariableChanged to monitor variable state during execution. This is especially useful when debugging Branch nodes that always take the same path:

storyFlow.OnVariableChanged += (variable, isGlobal) =>
{
    string scope = isGlobal ? "global" : "local";
    Debug.Log($"[StoryFlow] Variable changed [{scope}]: " +
              $""{variable.Name}" = {variable.Value} (type: {variable.Type})");
};

Check Unity Console

All StoryFlow plugin messages use the [StoryFlow] prefix. In the Unity Console window, use the search box to filter for "StoryFlow" to see only plugin-related messages. This includes:

• Initialization messages when the manager loads a project
• Import progress and results
• Node execution logs (when verbose logging is enabled)
• Variable change logs (when variable logging is enabled)
• Warnings for missing assets, null references, or invalid state
• Error messages for execution failures

Cross-Reference with the Editor

Many plugin errors mirror editor runtime errors. If you see an error in Unity, try playing the same script in the 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.

Use Live Sync for Rapid Iteration

When debugging, use Live Sync to push changes from the StoryFlow Editor to Unity without manually re-exporting. Fix a broken connection or update variable logic in the editor, save, and immediately test the fix in Unity.