Troubleshooting

This page provides detailed diagnostic steps for common issues. For quick answers, check the FAQ first.

Cannot Connect to UE Editor

Symptom: The NexusFlow status bar stays 🔴 red (disconnected), even though the UE Editor is running.

Possible causes:

• Version mismatch between the NexusFlow desktop app and UE plugin
• NexusFlow plugin is not enabled in the UE project
• Firewall or security software blocking communication
• Another NexusFlow instance is occupying the communication pipe

Diagnostic steps:

1. Check version compatibility: Make sure both the NexusFlow desktop app and UE plugin are updated to the latest version. Version mismatches are the most common cause of connection failures
2. Check plugin status: In UE, go to Edit > Plugins, search for "NexusFlow," and confirm the plugin is enabled
3. Rule out firewall interference: Temporarily disable your firewall or security software and test the connection
4. Check for multiple instances: Make sure only one NexusFlow process is running (check Task Manager)
5. Review logs:
   • NexusFlow log: %APPDATA%/cn.nexusflow.desktop/logs/tauri_debug.log
   • UE log: In <Project Directory>/Saved/Logs/, search for LogNexusFlow
6. Restart both applications: Close UE and NexusFlow, then relaunch them (startup order does not matter)

Quick check

Open NexusFlow's Settings > About page and look at the "Plugin Status" section to see if a UE installation is detected.

AI Not Responding or Showing Errors

Symptom: After sending a message, the AI doesn't reply, or the chat area displays an error.

Possible causes:

• No AI model configured, or validation has failed
• Invalid API Key or insufficient account balance
• Network cannot reach the AI provider's endpoint
• Custom Provider is misconfigured

Diagnostic steps:

1. Check model configuration: Go to Settings > AI Models and confirm at least one model is added and set as default
2. Test the model connection: Click the "Validate" button on the model card
3. If validation fails:
   • Verify the API Key is copied correctly (watch for leading/trailing spaces)
   • Confirm your provider account has sufficient balance
   • Test network connectivity:
     • OpenAI: Can you reach api.openai.com?
     • Anthropic: Can you reach api.anthropic.com?
     • DeepSeek: Can you reach api.deepseek.com?
     • Zhipu GLM: Can you reach open.bigmodel.cn?
     • MiniMax: Can you reach api.minimaxi.com?
     • Qwen: Can you reach dashscope.aliyuncs.com?
     • Kimi: Can you reach api.moonshot.cn?
4. If using a Custom Provider: Confirm the API URL and communication protocol are correct
5. Check logs: Open %APPDATA%/cn.nexusflow.desktop/logs/tauri_debug.log and search for error or failed

Anthropic users

Anthropic (Claude) models require Max Tokens to be set. Without it, API calls will fail. Check your model configuration.

Sidebar Chat Unavailable for a Long Time

Symptom: After opening the sidebar, the chat input remains disabled or shows a loading state for an extended period.

Possible causes:

• Internal AI service initialization delay
• Port conflict with another NexusFlow instance or another program

Diagnostic steps:

1. Wait for initialization: On first launch, the AI service needs roughly 10 seconds to initialize and will retry automatically
2. Check for multiple instances: Search for "NexusFlow" in Task Manager and close any extra instances
3. Check for port conflicts: Another program may have claimed the port
4. Restart the application: Fully close NexusFlow and relaunch it

Blueprint Behaves Abnormally After AI Operation

Symptom: After the AI modifies a Blueprint, compilation errors appear, connections are broken, or behavior is unexpected.

Possible causes:

• AI-generated operations aren't always perfect
• Invalid connections or missing required nodes may be produced
• Complex Blueprints may not be handled with full precision

Diagnostic steps:

1. Undo immediately: Press Ctrl+Z in UE to undo the most recent operation
2. Check error messages: Review the Blueprint compiler's error output for specifics
3. Undo multiple times: If one undo isn't enough, press Ctrl+Z several times to roll back further
4. Restore from version control: If undo doesn't help, revert the file via Git or another VCS

Important

Before letting the AI make significant Blueprint changes, save the Blueprint (Ctrl+S). That way you can always undo back to the save point if something goes wrong.

Prevention tips:

• Save important Blueprints before AI operations
• Use a version control system (e.g., Git) to manage Blueprint files
• Break large tasks into smaller steps instead of executing many changes at once
• Be as specific as possible when describing what you need

Global Hotkeys Not Working

Symptom: A global hotkey (e.g., toggle sidebar) has been set but doesn't respond when pressed.

Possible causes:

• Hotkey conflicts with another application
• Hotkey failed to register with the operating system
• Application wasn't restarted after the change

Diagnostic steps:

1. Check for conflicts: Make sure no other application (screenshot tool, input method, etc.) is using the same key combination
2. Try a different combination: Go to Settings > Hotkeys and pick a less common shortcut
3. Reset to default: Click the "Reset to Default" button to restore all hotkeys
4. Restart the application: Restart NexusFlow after changing hotkeys for them to take effect

Log File Locations

Log files are the most valuable source of diagnostic information when troubleshooting.

NexusFlow Logs

Log	Path
Main application log	%APPDATA%/cn.nexusflow.desktop/logs/tauri_debug.log

Opening the AppData directory

Type %APPDATA%/cn.nexusflow.desktop/ into the Windows File Explorer address bar and press Enter.

UE Plugin Logs

Log	Path
UE Editor log	<UE Project Directory>/Saved/Logs/*.log
Bridge debug log (Debug builds)	<UE Project Directory>/Saved/Logs/nexusflow_bridge_debug.log

• Search for the keyword LogNexusFlow in UE logs to filter NexusFlow plugin entries
• The Bridge debug log is only generated in Debug builds. In Release builds, Bridge output is merged into the standard UE log — search for [Bridge]

NexusFlow Setup Dialog in UE

Symptom: A "NexusFlow Setup" dialog pops up every time UE starts.

Explanation: This dialog appears when the NexusFlow plugin detects that the desktop app is not installed or the embedding model is not ready. It's a first-run helper, not an error.

Options:

What you want	Action
Set it up now	Click Download Model or Open Settings and follow the prompts
Set it up later	Click Later — the dialog will appear again on next startup
Never see it again	Click Don't Show Again — the dialog won't appear anymore

To re-enable the dialog after dismissing it:

1. Open %LOCALAPPDATA%/NexusFlow/config.json
2. Change "showSetupWizard" to true
3. Restart the UE Editor

Still stuck?

If none of the above steps resolved your issue:

1. Collect the relevant log files (NexusFlow log + UE log)
2. Write down the exact steps to reproduce the problem
3. Open an issue on GitHub Issues with this information attached