CoplayDev/unity-mcp · error · UnityConnectionError

HTTP error from server: {e.response.status_code} - {e.respon

Error message

HTTP error from server: {e.response.status_code} - {e.response.text}

What it means

Thrown by send_command() when the server returns a non-2xx HTTP status (raise_for_status fails). The message includes the status code and the raw response body. Unlike connection or timeout errors, this means the server was reached and actively rejected the request — bad params, internal server error, or a missing Unity instance.

Source

Thrown at Server/src/cli/utils/connection.py:122

                url,
                json=payload,
                timeout=timeout or cfg.timeout,
            )
            response.raise_for_status()
            return response.json()
    except httpx.ConnectError as e:
        raise UnityConnectionError(
            f"Cannot connect to Unity MCP server at {cfg.host}:{cfg.port}. "
            f"Make sure the server is running and Unity is connected.\n"
            f"Error: {e}"
        )
    except httpx.TimeoutException:
        raise UnityConnectionError(
            f"Connection to Unity timed out after {timeout or cfg.timeout}s. "
            f"Unity may be busy or unresponsive."
        )
    except httpx.HTTPStatusError as e:
        raise UnityConnectionError(
            f"HTTP error from server: {e.response.status_code} - {e.response.text}"
        )
    except Exception as e:
        raise UnityConnectionError(f"Unexpected error: {e}")


def run_command(
    command_type: str,
    params: Dict[str, Any],
    config: Optional[CLIConfig] = None,
    timeout: Optional[int] = None,
) -> Dict[str, Any]:
    """Synchronous wrapper for send_command.

    Args:
        command_type: The command type
        params: Command parameters
        config: Optional CLI configuration

View on GitHub (pinned to c21bf496bc)

Solutions

1. Read the status code and response body in the message to identify the cause (4xx vs 5xx).
2. For 4xx, correct the command params; verify CLI and server versions match.
3. For 5xx, inspect the server logs for the underlying exception.
4. Confirm the unity_instance (if set) is connected to the server.

Example fix

# before
# passing an invalid action
unity-mcp texture create --pattern bogus
# after
# use a supported value and check server logs on 5xx
unity-mcp texture create --pattern checkerboard

import httpx
r = httpx.post(url, json=payload, timeout=cfg.timeout)
if r.status_code >= 400:
    raise RuntimeError(f"server returned {r.status_code}: {r.text}")

try:
    return await send_command(cmd, params)
except UnityConnectionError as e:
    msg = str(e)
    if "HTTP error" in msg:
        # parse status code, surface body for 4xx/5xx triage
        ...
    raise

When it happens

Trigger: Posting a command with invalid params that the server rejects (400), a server-side exception (500), or hitting an endpoint that requires a unity_instance that is not connected (4xx). Also from auth/routing errors if the server is reverse-proxied.

Common situations: Malformed command payload, server bug producing a 500, or the target Unity instance disconnected so the server returns an error status. Common when the CLI version and server version disagree on the command schema.

Related errors

• Cannot connect to Unity MCP server at {cfg.host}:{cfg.port}.
• Connection to Unity timed out after {timeout or cfg.timeout}
• Unexpected error: {e}
• fal {phase} failed (status={res?.Status}): {detail}
• fal {phase} failed (status={res?.Status}): {detail}

AI-assisted analysis of CoplayDev/unity-mcp@c21bf496bc (2026-08-13). Data as JSON: /api/errors/ee1bed35fe0d72c8. Report an issue: GitHub.