From 1fbdda5acd734626b4bc13fd2fea482d44dc8d24 Mon Sep 17 00:00:00 2001 From: Anant Sharma <10895811+ananttheant@users.noreply.github.com> Date: Tue, 1 Sep 2026 13:59:47 +0100 Subject: [PATCH 1/2] docs: add troubleshooting entries for the Unity 6.5 editor hang and Codex resource reads MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Two failure modes that users reasonably misattribute to MCP for Unity. Unity's pre-release com.unity.ai.assistant package can livelock the AssetDatabase on Unity 6000.5.x, so the editor never opens and the bridge never arms — which reads as "MCP never connects". The non-obvious step in the fix is deleting packages-lock.json, since editing the manifest alone silently re-resolves the package. Codex exposes callable tools as mcp__unityMCP.* but wants the bare server key from resource discovery for resources/read, so agents following our instructions guess the tool namespace and get "unknown MCP server". Closes #1219 Closes #1220 --- website/docs/guides/troubleshooting.md | 35 ++++++++++++++++++++++++++ 1 file changed, 35 insertions(+) diff --git a/website/docs/guides/troubleshooting.md b/website/docs/guides/troubleshooting.md index baedd4e7d..600d837c6 100644 --- a/website/docs/guides/troubleshooting.md +++ b/website/docs/guides/troubleshooting.md @@ -146,6 +146,30 @@ Unity AI Assistant bundles `System.Collections.Immutable` v10, while MCP for Uni --- +## Editor hangs on load and the bridge never connects (Unity 6.5 + AI packages) + +If the Editor never finishes loading on **Unity 6000.5.x**, MCP for Unity can look like the culprit — the bridge never arms because the Editor never gets that far. + +*Reported by [@100yenadmin](https://github.com/CoplayDev/unity-mcp/issues/1219).* + +**Symptoms:** +- The Editor launches, gets through licensing and package registration, then spins at ~100% CPU on the main thread forever +- No Editor window ever appears, and the MCP for Unity bridge never connects +- Happens on every launch method — Unity Hub, CLI, and `-batchmode` +- A native stack of the spinning thread sits inside `AssetDatabase::InitialRefresh` + +**Cause:** +Unity's own pre-release `com.unity.ai.assistant` package (with its `com.unity.ai.inference` and `com.unity.asset-manager-for-unity` dependencies) can livelock the AssetDatabase during the initial import. This is a Unity bug, tracked as **UUM-132096** — not an MCP for Unity issue. + +**Fix:** +1. Remove `com.unity.ai.assistant`, `com.unity.ai.inference`, and `com.unity.asset-manager-for-unity` from `Packages/manifest.json`. +2. Delete `Packages/packages-lock.json`. This step is essential — the lock file re-resolves the packages even after the manifest edit, which makes the problem look intermittent. +3. Delete the `Library/` folder so the project reimports cleanly. + +**Note:** Disabling the package is not enough; the AI packages form an interlocking dependency chain that re-adds itself. See also the [DLL reference mismatch](#dll-reference-mismatch-with-unity-ai-assistant-package) section above, which covers a different problem caused by the same package. + +--- + ## "No Unity Instances Found" :::tip When in doubt, restart your client @@ -181,3 +205,14 @@ A: Start a new chat — the bad chat didn't pick up the MCP server configuration **Q: My MCP client keeps failing to launch the server even though `uv` is installed.** A: Some Windows machines have multiple `uv.exe` locations. Auto-config sometimes picks a less stable path, causing the launch to fail or auto-rewrite on every restart. Use **"Choose UV Install Location"** in the MCP for Unity window and pin the **WinGet Links shim** path (`%LOCALAPPDATA%\Microsoft\WinGet\Links\uv.exe`) — it's stable across uv upgrades. + +## FAQ — Codex + +**Q: Reading `mcpforunity://custom-tools` fails with `unknown MCP server 'mcp__unityMCP'`.** +A: Codex exposes callable tools and readable resources under different names. Tools are namespaced `mcp__unityMCP.*`, but generic resource reads want the bare server key returned by resource discovery — usually `unityMCP`. Call `list_mcp_resources` first and pass the server key it returns verbatim: + +```text +resources/read server: "unityMCP" uri: "mcpforunity://custom-tools" +``` + +The same applies to `mcpforunity://instances`. This naming split is a client-side convention, so check the discovery output rather than assuming the tool namespace also works for resources. From d0f14ef2fb57fe1b6b2ac050cef3588d490a0de3 Mon Sep 17 00:00:00 2001 From: Anant Sharma <10895811+ananttheant@users.noreply.github.com> Date: Tue, 1 Sep 2026 14:12:28 +0100 Subject: [PATCH 2/2] docs: attribute UUM-132096 to the package re-adding behaviour, not the livelock The Unity issue covers the AI packages' interlocking, self-re-adding dependency chain, which is the context the reporter cited it in. Calling it the tracking ticket for the AssetDatabase livelock itself overstated what it says. Addresses CodeRabbit review on #1360. --- website/docs/guides/troubleshooting.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/website/docs/guides/troubleshooting.md b/website/docs/guides/troubleshooting.md index 600d837c6..6e355a1ce 100644 --- a/website/docs/guides/troubleshooting.md +++ b/website/docs/guides/troubleshooting.md @@ -159,14 +159,14 @@ If the Editor never finishes loading on **Unity 6000.5.x**, MCP for Unity can lo - A native stack of the spinning thread sits inside `AssetDatabase::InitialRefresh` **Cause:** -Unity's own pre-release `com.unity.ai.assistant` package (with its `com.unity.ai.inference` and `com.unity.asset-manager-for-unity` dependencies) can livelock the AssetDatabase during the initial import. This is a Unity bug, tracked as **UUM-132096** — not an MCP for Unity issue. +Unity's own pre-release `com.unity.ai.assistant` package (with its `com.unity.ai.inference` and `com.unity.asset-manager-for-unity` dependencies) can livelock the AssetDatabase during the initial import. This is a Unity-side problem, not an MCP for Unity issue. **Fix:** 1. Remove `com.unity.ai.assistant`, `com.unity.ai.inference`, and `com.unity.asset-manager-for-unity` from `Packages/manifest.json`. 2. Delete `Packages/packages-lock.json`. This step is essential — the lock file re-resolves the packages even after the manifest edit, which makes the problem look intermittent. 3. Delete the `Library/` folder so the project reimports cleanly. -**Note:** Disabling the package is not enough; the AI packages form an interlocking dependency chain that re-adds itself. See also the [DLL reference mismatch](#dll-reference-mismatch-with-unity-ai-assistant-package) section above, which covers a different problem caused by the same package. +**Note:** Disabling the package is not enough; the AI packages form an interlocking dependency chain that re-adds itself — behaviour tracked in Unity issue **UUM-132096**. See also the [DLL reference mismatch](#dll-reference-mismatch-with-unity-ai-assistant-package) section above, which covers a different problem caused by the same package. ---