{"record":{"id":"3fa62d3708cfddbb","repo":"CoplayDev/unity-mcp","slug":"ping-unsuccessful","errorCode":null,"errorMessage":"Ping unsuccessful","messagePattern":"Ping unsuccessful","errorType":"exception","errorClass":"Exception","httpStatus":null,"severity":"error","filePath":"Server/src/transport/legacy/unity_connection.py","lineNumber":423,"sourceCode":"                        restore_timeout = self.sock.gettimeout()\n                        self.sock.settimeout(recv_timeout)\n                    try:\n                        t_recv_start = time.time()\n                        response_data = self.receive_full_response(self.sock)\n                        logger.info(\"[TIMING-STDIO] receive took %.3fs command=%s len=%d\", time.time() - t_recv_start, command_type, len(response_data))\n                        with contextlib.suppress(Exception):\n                            logger.debug(\n                                f\"recv {len(response_data)} bytes; mode={mode}\")\n                    finally:\n                        if restore_timeout is not None:\n                            self.sock.settimeout(restore_timeout)\n\n                # Parse\n                if command_type == 'ping':\n                    resp = json.loads(response_data.decode('utf-8'))\n                    if resp.get('status') == 'success' and resp.get('result', {}).get('message') == 'pong':\n                        return {\"message\": \"pong\"}\n                    raise Exception(\"Ping unsuccessful\")\n\n                resp = json.loads(response_data.decode('utf-8'))\n                if resp.get('status') == 'error':\n                    err = resp.get('error') or resp.get(\n                        'message', 'Unknown Unity error')\n                    raise Exception(err)\n                return resp.get('result', {})\n            except Exception as e:\n                logger.warning(\n                    f\"Unity communication attempt {attempt+1} failed: {e}\")\n                try:\n                    if self.sock:\n                        self.sock.close()\n                finally:\n                    self.sock = None\n\n                # Re-discover the port for this specific instance\n                try:","sourceCodeStart":405,"sourceCodeEnd":441,"githubUrl":"https://github.com/CoplayDev/unity-mcp/blob/c21bf496bca87d54e75bad048563c3adb1782081/Server/src/transport/legacy/unity_connection.py#L405-L441","documentation":"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.","triggerScenarios":"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.","commonSituations":"Port pointed at the wrong JSON-speaking listener, a partially-initialized bridge, or version skew where ping is handled differently.","solutions":["Verify the discovered/used port belongs to the MCPForUnity bridge (check ~/.unity-mcp status files and the port registry).","Restart the MCPForUnity bridge in Unity (Advanced Settings) and let it re-register.","Check the Unity console for bridge errors."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"# Confirm the port is the bridge before trusting a ping\nimport json\nfrom pathlib import Path\n\ndef port_is_bridge(port: int) -> bool:\n    for f in Path.home().joinpath('.unity-mcp').glob('unity-mcp-status-*.json'):\n        try:\n            if json.loads(f.read_text()).get('port') == port:\n                return True\n        except Exception:\n            continue\n    return False","typeGuard":"def is_ping_unsuccessful(e: BaseException) -> bool:\n    return isinstance(e, Exception) and str(e) == 'Ping unsuccessful'","tryCatchPattern":"try:\n    pong = conn.send_command('ping')\nexcept Exception as e:\n    if str(e) == 'Ping unsuccessful':\n        # wrong listener — re-resolve the port and reconnect\n        conn.disconnect()\n        stdio_port_registry.refresh()\n        conn.connect()\n        pong = conn.send_command('ping')\n    else:\n        raise","preventionTips":["Verify the port actually belongs to the MCPForUnity bridge before relying on ping.","Restart the bridge in Unity Advanced Settings if ping responses look malformed.","Check the Unity console for bridge errors after a ping failure."],"tags":["ping","protocol","handshake","wrong-port"],"backgroundTag":null,"analyzedSha":"c21bf496bca87d54e75bad048563c3adb1782081","analyzedAt":"2026-08-13T17:36:56.095Z","schemaVersion":2},"datasetVersion":"2026-08-13T19:17:28.613Z"}