{"record":{"id":"921f3a46eecfb84e","repo":"CoplayDev/unity-mcp","slug":"1","errorCode":"1","errorMessage":"--http-remote-hosted requires --api-key-validation-url or UNITY_MCP_API_KEY_VALIDATION_URL environment variable","messagePattern":"--http-remote-hosted requires --api-key-validation-url or UNITY_MCP_API_KEY_VALIDATION_URL environment variable","errorType":"console","errorClass":"SystemExit","httpStatus":null,"severity":"critical","filePath":"Server/src/main.py","lineNumber":848,"sourceCode":"        config.api_key_cache_ttl = 300.0\n\n    # Service token for authenticating to validation endpoint\n    config.api_key_service_token_header = (\n        args.api_key_service_token_header\n        or os.environ.get(\"UNITY_MCP_API_KEY_SERVICE_TOKEN_HEADER\")\n    )\n    config.api_key_service_token = (\n        args.api_key_service_token\n        or os.environ.get(\"UNITY_MCP_API_KEY_SERVICE_TOKEN\")\n    )\n\n    # Validate: remote-hosted HTTP mode requires API key validation URL\n    if config.http_remote_hosted and config.transport_mode == \"http\" and not config.api_key_validation_url:\n        logger.error(\n            \"--http-remote-hosted requires --api-key-validation-url or \"\n            \"UNITY_MCP_API_KEY_VALIDATION_URL environment variable\"\n        )\n        raise SystemExit(1)\n\n    http_url = os.environ.get(\"UNITY_MCP_HTTP_URL\", args.http_url)\n    parsed_url = urlparse(http_url)\n\n    # Allow individual host/port to override URL components\n    http_host = args.http_host or os.environ.get(\n        \"UNITY_MCP_HTTP_HOST\") or parsed_url.hostname or \"127.0.0.1\"\n\n    # Safely parse optional environment port (may be None or non-numeric)\n    _env_port_str = os.environ.get(\"UNITY_MCP_HTTP_PORT\")\n    try:\n        _env_port = int(_env_port_str) if _env_port_str is not None else None\n    except ValueError:\n        logger.warning(\n            \"Invalid UNITY_MCP_HTTP_PORT value '%s', ignoring\", _env_port_str)\n        _env_port = None\n\n    http_port = args.http_port or _env_port or parsed_url.port or 8080","sourceCodeStart":830,"sourceCodeEnd":866,"githubUrl":"https://github.com/CoplayDev/unity-mcp/blob/c21bf496bca87d54e75bad048563c3adb1782081/Server/src/main.py#L830-L866","documentation":"A fatal startup validation in main.py: when --http-remote-hosted is enabled AND transport_mode is 'http' AND no API key validation URL is configured, the server aborts with SystemExit(1). Remote-hosted mode exposes the server to multiple users over the network, so it mandates an external API key validation endpoint to authenticate clients. Without it, the server refuses to start — this is a security guardrail, not a runtime error.","triggerScenarios":"Launching the server with `--http-remote-hosted --transport http` but omitting `--api-key-validation-url`; setting UNITY_MCP_HTTP_REMOTE_HOSTED=1 and UNITY_MCP_TRANSPORT=http env vars without UNITY_MCP_API_KEY_VALIDATION_URL; a deployment script that enables remote-hosted mode but forgets to pass the validation URL.","commonSituations":"Migrating from local (loopback) to a remote-hosted deployment and forgetting the auth dependency; a CI/deploy script that sets remote-hosted via env but not the validation URL; misreading the docs and assuming the validation URL is optional.","solutions":["Provide the validation URL via CLI flag: add `--api-key-validation-url https://your-auth.example.com/validate` to the launch command.","Or set the environment variable: UNITY_MCP_API_KEY_VALIDATION_URL=https://your-auth.example.com/validate.","If you did not intend remote-hosted mode, remove --http-remote-hosted / UNITY_MCP_HTTP_REMOTE_HOSTED from the launch config.","Verify the validation endpoint is reachable and returns 200 for valid keys before starting the server."],"exampleFix":"# before\npython -m src.main --transport http --http-remote-hosted\n# after\npython -m src.main --transport http --http-remote-hosted \\\n  --api-key-validation-url https://auth.example.com/validate","handlingStrategy":"validation","validationCode":"# Validate required config before launching the server\nimport os\nhttp_remote_hosted = os.environ.get(\"UNITY_MCP_HTTP_REMOTE_HOSTED\", \"\").lower() in (\"1\", \"true\", \"yes\")\ntransport = os.environ.get(\"UNITY_MCP_TRANSPORT\", \"stdio\")\nvalidation_url = os.environ.get(\"UNITY_MCP_API_KEY_VALIDATION_URL\", \"\")\n\nif http_remote_hosted and transport == \"http\" and not validation_url:\n    raise SystemExit(\n        \"Remote-hosted HTTP mode requires UNITY_MCP_API_KEY_VALIDATION_URL. \"\n        \"Set it or disable --http-remote-hosted.\"\n    )","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Always pair --http-remote-hosted with --api-key-validation-url in launch scripts.","Use a deployment checklist that verifies all remote-hosted prerequisites before start.","Document the dependency in your deployment scripts to prevent omission."],"tags":["config","startup","auth","remote-hosted","system-exit"],"backgroundTag":null,"analyzedSha":"c21bf496bca87d54e75bad048563c3adb1782081","analyzedAt":"2026-08-13T17:36:56.095Z","schemaVersion":2},"datasetVersion":"2026-08-13T19:17:28.613Z"}