{"record":{"id":"192ebf52cf1e054d","repo":"CoplayDev/unity-mcp","slug":"mcp-for-unity-requires-framing-1-got-text-r","errorCode":null,"errorMessage":"MCP for Unity requires FRAMING=1, got: {text!r}","messagePattern":"MCP for Unity requires FRAMING=1, got: (.+?)","errorType":"exception","errorClass":"ConnectionError","httpStatus":null,"severity":"critical","filePath":"Server/src/transport/legacy/unity_connection.py","lineNumber":103,"sourceCode":"                                break\n                            buf.extend(chunk)\n                            if b\"\\n\" in buf:\n                                break\n                        except socket.timeout:\n                            break\n                    text = bytes(buf).decode('ascii', errors='ignore').strip()\n\n                    if 'FRAMING=1' in text:\n                        self.use_framing = True\n                        logger.debug(\n                            'MCP for Unity handshake received: FRAMING=1 (strict)')\n                    else:\n                        if require_framing:\n                            # Best-effort plain-text advisory for legacy peers\n                            with contextlib.suppress(Exception):\n                                self.sock.sendall(\n                                    b'MCP for Unity requires FRAMING=1\\n')\n                            raise ConnectionError(\n                                f'MCP for Unity requires FRAMING=1, got: {text!r}')\n                        else:\n                            self.use_framing = False\n                            logger.warning(\n                                'MCP for Unity handshake missing FRAMING=1; proceeding in legacy mode by configuration')\n                finally:\n                    self.sock.settimeout(config.connection_timeout)\n                return True\n            except Exception as e:\n                logger.error(f\"Failed to connect to Unity: {str(e)}\")\n                try:\n                    if self.sock:\n                        self.sock.close()\n                except Exception:\n                    pass\n                self.sock = None\n                return False\n","sourceCodeStart":85,"sourceCodeEnd":121,"githubUrl":"https://github.com/CoplayDev/unity-mcp/blob/c21bf496bca87d54e75bad048563c3adb1782081/Server/src/transport/legacy/unity_connection.py#L85-L121","documentation":"Raised during the stdio TCP handshake (unity_connection.py:103). After connecting, the server reads the first line and expects it to contain the literal 'FRAMING=1'. When config.require_framing is True (the default) and the line lacks it, the server sends a best-effort advisory to the peer and refuses the connection, embedding whatever text was actually received as {text!r}.","triggerScenarios":"send_command -> connect() where the peer on the discovered port is either an older Unity editor that does not speak the framing protocol, a different service entirely, or a Unity bridge still mid-boot that wrote something other than the FRAMING=1 banner.","commonSituations":"Version skew between the Python server and the MCPForUnity Unity package (server newer/stricter than the editor), a stale port pointed at another listener, or Unity not fully initialized when the first command fires.","solutions":["Update the MCPForUnity Unity package to a version that matches the Python server so it emits FRAMING=1.","Confirm the resolved port actually belongs to the MCPForUnity bridge (check ~/.unity-mcp status files / port registry), not another process.","Wait for Unity to finish booting before issuing commands.","As a temporary interop escape hatch, set config.require_framing=False to allow legacy (unframed) mode — the server then logs a warning and proceeds."],"exampleFix":"// before — strict (default)\n# config.require_framing == True  -> raises on legacy peers\n\n// after — opt into legacy interop explicitly\nfrom core.config import config\nconfig.require_framing = False","handlingStrategy":"validation","validationCode":"from core.config import config\n\ndef framing_interop_ok() -> bool:\n    # True only if the peer is known to emit FRAMING=1 (matched versions)\n    return config.require_framing or config.require_framing is False  # see note","typeGuard":"def is_framing_handshake_error(e: BaseException) -> bool:\n    return (isinstance(e, ConnectionError)\n            and 'requires FRAMING=1' in str(e))","tryCatchPattern":"try:\n    conn.connect()\nexcept ConnectionError as e:\n    if 'requires FRAMING=1' in str(e):\n        # version mismatch — either upgrade the Unity package or allow legacy mode\n        from core.config import config\n        config.require_framing = False\n        conn.sock = None\n        conn.connect()\n    else:\n        raise","preventionTips":["Keep the Python server and the MCPForUnity Unity package on the same release line.","Confirm the discovered port is the bridge, not another listener, before issuing commands.","Wait for Unity to finish importing/booting before the first command."],"tags":["handshake","framing","version-mismatch","stdio","protocol"],"backgroundTag":null,"analyzedSha":"c21bf496bca87d54e75bad048563c3adb1782081","analyzedAt":"2026-08-13T17:36:56.095Z","schemaVersion":2},"datasetVersion":"2026-08-13T19:17:28.613Z"}