From 9fcf0416c77b854afe6c4ab0c291f5f3a79923f5 Mon Sep 17 00:00:00 2001 From: haranishi <223786623+haranishi@users.noreply.github.com> Date: Mon, 12 Oct 2026 07:48:55 +0900 Subject: [PATCH] fix: explain how to recover a missing Unity session --- Server/src/transport/plugin_hub.py | 7 +++++++ website/docs/guides/troubleshooting.md | 15 +++++++++++++++ 2 files changed, 22 insertions(+) diff --git a/Server/src/transport/plugin_hub.py b/Server/src/transport/plugin_hub.py index 5ab37a2f5c..01a6946d6c 100644 --- a/Server/src/transport/plugin_hub.py +++ b/Server/src/transport/plugin_hub.py @@ -846,6 +846,13 @@ def _unavailable_retry_response(reason: str = "no_unity_session") -> dict[str, A return MCPResponse( success=False, error="Unity session not available; please retry", + message=( + "The MCP server is reachable, but the requested Unity session is unavailable. " + "Open Unity and start its MCP session. If the editor is already open, " + "bring it to the foreground and check for pending dialogs, then retry." + if reason == "no_unity_session" + else None + ), hint="retry", data={"reason": reason, "retry_after_ms": 250}, ).model_dump() diff --git a/website/docs/guides/troubleshooting.md b/website/docs/guides/troubleshooting.md index 07e53f905a..0c8f6d1930 100644 --- a/website/docs/guides/troubleshooting.md +++ b/website/docs/guides/troubleshooting.md @@ -216,6 +216,21 @@ If restarting doesn't fix it: --- +## HTTP server responds, but the Unity session is unavailable + +If a tool returns `Unity session not available; please retry` with +`data.reason: no_unity_session`, the MCP server has handled the request, but the +requested Unity bridge session is unavailable. Its message includes recovery +steps; the machine-readable `hint: retry` and retry interval remain unchanged. + +- If Unity is compiling or reloading, allow it to finish before retrying. +- Open Unity and confirm that its MCP for Unity session is started. +- If the editor is already open in the background, bring it to the foreground + and check for pending dialogs before retrying. +- Read `mcpforunity://instances` again to confirm that the editor has registered. + +--- + ## Unity takes focus while tests are running The server may briefly focus Unity when a running test has not reported progress,