CoplayDev/unity-mcp · error · UnityConnectionError

HTTP error from server

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.

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
• Connection to Unity timed out after
• Unexpected error
• Connection to Unity timed out after
• Connection to Unity timed out while listing instances…

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

Appendix: 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)