CoplayDev/unity-mcp · error · Exception

Ping unsuccessful

Error message

Ping unsuccessful

What it means

Raised by send_command (unity_connection.py:423) for a ping. The response parsed as JSON but was not {"status":"success","result":{"message":"pong"}}. The socket and JSON are fine, but the protocol payload is wrong — typically meaning the port is not actually the MCPForUnity bridge.

Source

Thrown at Server/src/transport/legacy/unity_connection.py:423

                        restore_timeout = self.sock.gettimeout()
                        self.sock.settimeout(recv_timeout)
                    try:
                        t_recv_start = time.time()
                        response_data = self.receive_full_response(self.sock)
                        logger.info("[TIMING-STDIO] receive took %.3fs command=%s len=%d", time.time() - t_recv_start, command_type, len(response_data))
                        with contextlib.suppress(Exception):
                            logger.debug(
                                f"recv {len(response_data)} bytes; mode={mode}")
                    finally:
                        if restore_timeout is not None:
                            self.sock.settimeout(restore_timeout)

                # Parse
                if command_type == 'ping':
                    resp = json.loads(response_data.decode('utf-8'))
                    if resp.get('status') == 'success' and resp.get('result', {}).get('message') == 'pong':
                        return {"message": "pong"}
                    raise Exception("Ping unsuccessful")

                resp = json.loads(response_data.decode('utf-8'))
                if resp.get('status') == 'error':
                    err = resp.get('error') or resp.get(
                        'message', 'Unknown Unity error')
                    raise Exception(err)
                return resp.get('result', {})
            except Exception as e:
                logger.warning(
                    f"Unity communication attempt {attempt+1} failed: {e}")
                try:
                    if self.sock:
                        self.sock.close()
                finally:
                    self.sock = None

                # Re-discover the port for this specific instance
                try:

View on GitHub (pinned to c21bf496bc)

Solutions

1. Verify the discovered/used port belongs to the MCPForUnity bridge (check ~/.unity-mcp status files and the port registry).
2. Restart the MCPForUnity bridge in Unity (Advanced Settings) and let it re-register.
3. Check the Unity console for bridge errors.

# Confirm the port is the bridge before trusting a ping
import json
from pathlib import Path

def port_is_bridge(port: int) -> bool:
    for f in Path.home().joinpath('.unity-mcp').glob('unity-mcp-status-*.json'):
        try:
            if json.loads(f.read_text()).get('port') == port:
                return True
        except Exception:
            continue
    return False

def is_ping_unsuccessful(e: BaseException) -> bool:
    return isinstance(e, Exception) and str(e) == 'Ping unsuccessful'

try:
    pong = conn.send_command('ping')
except Exception as e:
    if str(e) == 'Ping unsuccessful':
        # wrong listener — re-resolve the port and reconnect
        conn.disconnect()
        stdio_port_registry.refresh()
        conn.connect()
        pong = conn.send_command('ping')
    else:
        raise

When it happens

Trigger: send_command('ping') connecting to a service that returns valid JSON but isn't the bridge (another localhost JSON API), or a stale/mismatched bridge whose ping envelope differs from the expected pong.

Common situations: Port pointed at the wrong JSON-speaking listener, a partially-initialized bridge, or version skew where ping is handled differently.

Related errors

• MCP for Unity requires FRAMING=1, got: {text!r}
• Unexpected handshake from server: {line!r}
• Unexpected handshake from server: {line!r}
• Invalid framed length: {payload_len}
• Invalid frame length: {length}

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