Troubleshooting

Ports 52342 to 52350

Symptom: hayba_check_ue_status says the editor is not connected, or the agent edits a different editor than the one you are watching.

The plugin listens on port 52342. If that port is taken, usually by a second editor, it tries 52343, 52344 and so on up to 52350, and writes the port it chose to <YourProject>/Saved/HaybaMCP/instances/<pid>.json. The server finds that file by searching upward from its own working directory. If it finds none, it uses 52342.

1. Check the editor's Output Log for LogHaybaMCP: TCP server started on port. If it says no free port in 52342-52350, close other editors or whatever holds those ports.
2. Start your MCP client from the project folder, so the server can find the instance file.
3. Or pin the port in your client config with the UE_TCP_PORT environment variable:

{
  "mcpServers": {
    "hayba-toolkit": {
      "command": "node",
      "args": ["C:\\dev\\hayba\\mcp-tools\\hayba-mcp\\dist\\index.js"],
      "env": { "UE_TCP_PORT": "52343" }
    }
  }
}

The server reconnects if the editor restarts, and looks up the port again each time. The plugin accepts up to 16 client connections at once.

Plugin does not load

Symptom: Unreal says the HaybaMCPToolkit module is missing or was built with a different engine version, or the Hayba tab is not in the Tools menu.

Hayba ships as C++ source. Its binaries must be compiled for the exact engine version that opens the project. Binaries built for Unreal Engine 5.8 do not load in 5.7, and the other way round. The plugin descriptor does not pin an engine version, so it is the build, not the descriptor, that has to match.

1. Close the editor.
2. Right-click the .uproject file, choose Switch Unreal Engine version if needed, then Generate Visual Studio project files.
3. Build the Development Editor configuration in Visual Studio and read the first error in the build output if it fails.

Most development and testing happens on 5.8. If the plugin fails to compile on 5.7, open an issue with the first compiler error and your exact engine version.

Other causes:

• The link is broken. If you moved your clone, Plugins\HaybaMCPToolkit points nowhere. Delete the link and run mklink /D again.
• A dependency plugin is disabled. The toolkit needs PCG, Python Editor Script Plugin, Web Browser Widget, Data Validation and Enhanced Input. Enable them under Edit, Plugins.
• A satellite plugin reports unknown commands. GAS commands need both HaybaMCPGAS and the engine's GameplayAbilities plugin.

Node.js not found

Symptom: your MCP client cannot start the server, or the in-editor chat cannot send and the Output Log shows Node.js not found.

• Your MCP client runs node from your PATH. Run node --version in a new terminal; it must print 22.5 or newer. If your client does not see your PATH, put the full path to node.exe in command.
• The editor plugin does not search PATH. It looks for C:\Program Files\nodejs\node.exe and C:\Program Files (x86)\nodejs\node.exe. Version managers install elsewhere. Install Node.js with the official installer in its default folder, then restart the editor.
• Server crashes at startup with a native or sqlite error: your Node.js is older than 22.5. Upgrade it.
• MCP server not found at: means the plugin cannot find dist/index.js. Build the server, or set SidecarEntryPath as shown in Getting started.

Stale build after an update

Symptom: after git pull, tools are missing, behave as before, or a tool the docs describe returns unknown_tool.

Your client runs the compiled server in dist/, not the TypeScript source. Pulling new source changes nothing until you rebuild:

npm install
npm --prefix mcp-tools/hayba-mcp run build:server

1. Restart the server in your client. In Claude Code, run /mcp and reconnect, or restart the session.
2. Restart the in-editor chat's server too. The plugin reuses whatever already listens on port 7821, so close the editor and end any leftover node.exe for Hayba before you reopen it.
3. If the plugin's C++ changed, close the editor and rebuild the project. A running editor keeps the old plugin loaded.

hayba_check_ue_status reports the plugin version, and the server prints its own version when it starts. They should match.

Live Coding and class layout

Symptom: the editor crashes with an access violation soon after a Live Coding compile.

Live Coding patches function bodies in a running editor. It cannot safely change a class's layout: adding or removing members, changing a UPROPERTY or UFUNCTION, or changing virtual functions. Patching such a change in leaves old objects with the old layout, and the editor crashes when it touches them.

• For changes inside function bodies, Live Coding is fine. An agent can trigger it with editor_live_compile.
• For any change to a class declaration in a header, close the editor and do a full build.
• Always rebuild with the editor closed after updating Hayba itself.

Live Coding errors are written to %LOCALAPPDATA%\UnrealBuildTool\Log.txt, not to the editor's Output Log.

Editor busy or timeouts

Symptom: calls fail with Timeout waiting for response, or everything slows to a crawl.

All editor work runs on the game thread, a few commands per frame. Anything that holds the game thread holds every command behind it. The server gives up on a reply after 30 seconds by default. Common causes:

• A modal dialog is open, such as a save prompt, a compile error or a message box. Commands wait until someone closes it. Look at the editor.
• Shaders are compiling after a material change or a new map. Have the agent call wait_for_shaders or wait_for_idle first.
• A long Python script holds the thread for its whole deadline: 5 seconds by default, up to 60 with an exclusive lease.
• A large cook or build started by build_* or test_run. These run as background jobs; poll build_status instead of waiting on the call.
• The editor window is minimised or in the background. Unreal throttles background editors, which slows every frame. Keep it visible during long runs.

editor_get_state shows Live Coding, shader and save activity, builds in progress and editor health in one call.

Refused commands

A refused command did not run. The code says why.

Logs

The server and the plugin redact secrets, such as API keys and tokens, before they log tool results. Check a log yourself before you share it.