# Troubleshooting

Fix common Godot MCP problems, from an addon that does not load or compile to an empty Extensions list, missing tools, reload errors and .NET 10 crashes.

_Last updated: 2026-11-04_

Most Godot MCP problems come from one of four places: the wrong Godot build, a `.csproj` that does not match the addon, a C# assembly that was not built, or an AI client that is not pointed at the right server. Work through the section that matches what you see. If you are stuck, raise the dock's **Log Level** to `Debug`, reproduce the problem and read the Output panel.

## The addon does not load

### "Unable to load addon script" on first open

Godot instantiates enabled addons as soon as the editor starts. On the very first open of a C# project that was never built, there is no assembly yet, so Godot reports it cannot load `res://addons/godot_mcp/Editor/GodotMcpPlugin.cs` and disables the addon.

Fix: build first, then enable the plugin again in **Project, Project Settings, Plugins**.

```bash
godot-cli build ./MyGodotProject
godot-cli open ./MyGodotProject
```

`godot-cli open` always builds before it starts the editor, so it avoids this problem.

### The addon does not compile

- You are using the standard Godot build. Godot MCP needs the **.NET (mono)** build of Godot 4.3 or newer.
- The `.csproj` is missing the NuGet packages, or has different versions than the addon you installed. Rerun `godot-cli install-plugin`, or copy the block from [Installation](https://ai-game.dev/docs/wiki/godot/installation#nuget-packages) with the versions of your addon release.
- The project has no `.csproj`. Create the C# solution from Godot, or use `godot-cli create-project --dotnet` for a new project.
- The .NET 8 SDK is not installed or not on `PATH`.

### FileNotFoundException for a NuGet assembly

Godot does not resolve a project's NuGet packages in the editor by itself; the addon does that by reading the build's `.deps.json` and your NuGet cache. If an assembly is still not found, run `dotnet restore` and build again. If the problem stays, delete `.godot/mono/temp/obj` and `.godot/mono/temp/bin` and rebuild: a stale build output is the usual cause.

## A game started with Play cannot create C# scripts

Symptom: every C# script fails with "Cannot instantiate C# script because the associated class could not be found", after a `TypeLoadException` naming an `EditorPlugin` class. Your `.csproj` is missing `<EnableDynamicLoading>true</EnableDynamicLoading>`, so the package assemblies are not copied next to the game assembly. Add it to the `<PropertyGroup>` next to `<TargetFramework>` and rebuild. `godot-cli install-plugin` and `create-project` set it for you.

## The Extensions list is empty

The dock reads the extension catalog from your compiled project. Your `.csproj` needs this line, then a rebuild:

```xml
<EmbeddedResource Include="addons/godot_mcp/extensions.catalog.json" LogicalName="Godot-MCP.extensions.catalog.json" />
```

The `LogicalName` must be exactly `Godot-MCP.extensions.catalog.json`. If the dock says no `.csproj` was found, the addon is not inside a Godot C# project. See [Extensions](https://ai-game.dev/docs/wiki/godot/extensions#catalog).

## The editor does not connect

- **Cloud mode, not signed in.** Click **Authorize** in the dock, or run `godot-cli login`. The dock shows your sign-in status.
- **Overridden by environment.** A yellow note "Overridden by environment (GODOT\_MCP\_\*)" means a variable or a `.env` file forces the mode or host, and changes in the dock do nothing. Remove the variable or change it.
- **Custom mode, no server.** Click **Start Server** in the dock, or start your own server. When offline, the server download fails with a warning in the Output panel and no local server starts; use Cloud mode or run a server you already have.
- **Custom mode with `oauth` on a remote host.** The addon sends your account token only to a localhost server. For other hosts set `GODOT_MCP_TOKEN`, otherwise the connection fails with "Refusing to send your ai-game.dev account token".

Check from a terminal with `godot-cli status ./MyGodotProject` and `godot-cli wait-for-ready ./MyGodotProject`.

## The AI agent sees no Godot tools

- The agent was started before its config was written. Restart it, or reload its MCP servers.
- Claude Code reads `.mcp.json` from the folder it starts in. Start it in the project folder, or write the config where you start it.
- Several editors are connected and the agent uses the plain `/mcp` URL. Use the pinned URL that `setup-mcp` writes by default, so the agent reaches the right project.
- The config points at another server than the editor (cloud vs local). Rerun `godot-cli setup-mcp <agent>` after you change mode, or click **Reconfigure** in the dock.
- Tools are hidden. Check the dock's MCP features section or `godot-cli configure --list`. A hidden tool is not listed to the agent.

## Tool calls fail during a C# rebuild

Godot reloads the project's C# assembly about half a second after the built DLL changes (`script-build`, the Build button or a `dotnet build`). The addon is part of that assembly, so it is torn down, rebuilt and reconnects within a few seconds. Around a reload, new calls are refused with a retryable error ("Godot is about to reload the project's C# assembly … Retry in a few seconds"). Wait and retry; `script-build` delivers its result after the reload.

## The editor crashes or hangs after a reload on .NET 10

This is a .NET runtime bug (dotnet/runtime#135441). Until the .NET 10 servicing fix ships, set this environment variable for the editor process and restart Godot:

```text
DOTNET_ThreadPool_ThreadsToKeepAlive=-1
```

On Windows you can set it with `setx DOTNET_ThreadPool_ThreadsToKeepAlive -1`. Editors started by `godot-cli open` or `exec` get it automatically. Remove it once your .NET runtime includes the fix.

## Calls go to an old build

If tool calls behave like an older version of your code, more than one editor may be connected for the same project, for example a forgotten headless editor. Close the extra ones (`godot-cli close --owned-only` closes editors that `godot-cli` started) and keep one editor connected.

## A build fails with MissingMethodException

The project's `Godot.NET.Sdk` version should match the editor you run. A project built against 4.3 can throw `MissingMethodException` on a 4.4 or newer editor where APIs changed. Update the `Sdk="Godot.NET.Sdk/…"` version in your `.csproj` to your editor version and rebuild.

## Still stuck

Check the [FAQ](https://ai-game.dev/docs/wiki/godot/faq) and the site [FAQ](https://ai-game.dev/docs/faq), or report the problem on the [Godot-MCP issue tracker](https://github.com/IvanMurzak/Godot-MCP/issues) with the Output panel log and your Godot, .NET and addon versions.

---

Source (HTML): https://ai-game.dev/docs/wiki/godot/troubleshooting