# Troubleshooting Fix common Unreal MCP problems - plugin not loading, bridge missing, connection stuck, AI agent without Unreal tools, stale builds and tool errors. _Last updated: 2026-11-04_ This page lists the problems people hit most often with Unreal MCP and how to fix them. Start with the quick checks, then jump to the matching section. ## Quick checks 1. **Is the plugin loaded?** The Output Log should contain `[Unreal-MCP] plugin loaded` after the editor starts. 2. **What does the window say?** Open **Tools**, **AI Game Developer** and read the status line (Connected, Connecting, Reconnecting, Disconnected or No MCP bridge). 3. **What does the CLI see?** Run `unreal-mcp-cli status --path ./YourProject`. 4. **Read the log.** Use **Open log file** in the window, filter the Output Log by the `LogUnrealMcp` category, or ask the agent for `console | where Verbosity == "Error"`. ## The plugin does not load If there is no `[Unreal-MCP] plugin loaded` line, the editor module failed to start. - Look in the Output Log for a start-up error from the plugin or a broken `.uplugin`. - Make sure the project is a **C++ project** with a working compiler toolchain. See [Installation](https://ai-game.dev/docs/wiki/unreal/installation#requirements). - If Unreal says modules are missing or the plugin is incompatible, let it rebuild, or open the project with `unreal-mcp-cli open ./YourProject`, which builds the native modules first and dismisses those prompts. ## An update has no effect Unreal's incremental build can keep old plugin code when the plugin's source changes but its old `Intermediate/` folder survives. - Update with `unreal-mcp-cli update ./YourProject`, which cleans the build cache by default. - After a manual copy: close the editor, delete `Plugins/UnrealMCP/Intermediate/` and the C++ files in `Plugins/UnrealMCP/Binaries/` (keep `Binaries/ThirdParty/`), then reopen. ## "No MCP bridge" or the bridge keeps restarting The plugin needs its bridge process, `unreal-mcp-bridge`. The window shows the bridge state and a restart count. - If the log says `no sidecar binary resolved for rid `, no bridge was found. - **App or CLI install:** the bridge is bundled. Re-install with `unreal-mcp-cli install-plugin ./YourProject` (or from the app); the package may be missing your platform. - **Source checkout:** build one with `unreal-mcp-cli bootstrap-local ./YourProject`, or set `UNREAL_MCP_BRIDGE_PATH`. - Click **Restart bridge** in the window footer after fixing the cause. ## Stuck on "Connecting" or "Reconnecting" - **Cloud mode:** check you are signed in. If the window shows "Sign in required", your saved sign-in expired; click **Authorize** and approve the new code. - Check that the machine can reach ai-game.dev (proxy or firewall rules). - **Custom mode:** make sure the local server is running (**Start** in the MCP server card, or `--start-server`) and that the **Server URL** points at it. - Use **Disconnect**, then **Connect**, or **Restart bridge**. ## Local server says "No connected clients" If a local `gamedev-mcp-server` logs `No connected clients. Retrying` and then answers with HTTP 500, the editor is still in **Cloud** mode and connected to ai-game.dev instead of your local server. Switch to **Custom** in the window, set `UNREAL_MCP_CONNECTION_MODE=Custom`, or pass `--connection-mode Custom` (or `--host`) to `unreal-mcp-cli open`. ## The AI agent has no Unreal tools - Check the agent's config: run `unreal-mcp-cli setup-mcp --path ./YourProject --dry-run` and compare, or click **Configure** (or **Reconfigure**) in the AI agent section. - Restart or reload the agent after the config changes. Many clients read MCP configs only at start-up. - Claude Code reads `.mcp.json` from the folder you start it in; start it in the project folder. - If you configured with `setup-mcp` before ever opening the editor, the config may point at `localhost` instead of the cloud. Open the project once, then run `setup-mcp` again, or pass `--url`. - Check the **AI agents** row in the Connection section. If your agent is not listed, it is not connected to the same server as the editor. - If you hid tools in the **MCP Tools** window or set `UNREAL_MCP_TOOLS`, the agent sees fewer tools. ## The agent reaches the wrong editor With several editors on one account, use the project-pinned URL (`/mcp/p/`), which `setup-mcp` writes by default. Re-run `setup-mcp` without `--no-pin`. See [Connecting AI clients](https://ai-game.dev/docs/wiki/unreal/connecting-ai-clients#pinned-url). ## 401 errors in the agent - In Cloud mode, a URL-only config needs the agent to sign in itself. Either let it run its OAuth sign-in, or sign the machine in (`unreal-mcp-cli login`) and run `setup-mcp` again so the config carries a project key. - If the project key was revoked, use **Regenerate key** in the editor or `setup-mcp --regenerate-key`. - In Custom mode with **token** auth, the config must carry the same token as the editor. Use **Reconfigure** after generating a new token. ## Tool calls time out One tool call may run for 5 minutes by default. Raise `UNREAL_MCP_TOOL_TIMEOUT` (milliseconds) for long Python scripts or big imports. `python-execute` also has its own `timeout` (default 30 seconds) that the agent can set per call. ## Screenshot tools return an error Pixel capture needs a GPU-backed editor. Under `-nullrhi` the screenshot tools return a structured error. `unreal-mcp-cli exec` and `open --headless` start editors that render off-screen, so captures still work there. ## Python tools fail `python-execute` uses Unreal's Python Editor Script Plugin, which Unreal MCP enables. If Python is unavailable, check that the plugin is enabled in **Edit, Plugins**. Errors point at lines of `snippet.py`, which is the code the agent sent. ## Extension does not show up - Extensions need Unreal Engine 5.7 or later and Unreal MCP 0.26.0 or later. - After installing, the extension must be compiled: reopen the editor, use `--build`, or **Compile (Live Coding)** in the Extensions section. - Check that the extension is enabled in the Extensions section. ## Still stuck? - See the [FAQ](https://ai-game.dev/docs/wiki/unreal/faq) and the general [FAQ](https://ai-game.dev/docs/faq). - Use **Help / Talk** in the window to ask on Discord, or **Bug Report** to open a GitHub issue. Include the Unreal version, your OS, the window's status line and the relevant log lines (never your tokens). --- Source (HTML): https://ai-game.dev/docs/wiki/unreal/troubleshooting