{"record":{"id":"4002b9bcd3aa7fcf","repo":"iflytek/astron-agent","slug":"service-port-key-is-not-set","errorCode":null,"errorMessage":"SERVICE_PORT_KEY is not set","messagePattern":"SERVICE_PORT_KEY is not set","errorType":"console","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"core/plugin/link/app/start_server.py","lineNumber":121,"sourceCode":"            asyncio.run(setup_watchdog())\n        except (ModuleNotFoundError, ImportError):\n            pass\n        except Exception as e:\n            print(f\"[Service] ⚠️  gateway watchdog setup exception:{str(e)}\")\n\n    @staticmethod\n    def start_uvicorn() -> None:\n        \"\"\"\n        Start the Uvicorn ASGI server with configuration loaded from environment\n        variables.\n\n        This method creates and starts a Uvicorn server instance using configuration\n        parameters such as host, port, worker count, reload settings, and WebSocket\n        ping intervals retrieved from environment variables.\n        \"\"\"\n        service_port = os.getenv(const.SERVICE_PORT_KEY)\n        if not service_port:\n            raise ValueError(\"SERVICE_PORT_KEY is not set\")\n        uvicorn_config = uvicorn.Config(\n            app=spark_link_app(),\n            host=\"0.0.0.0\",\n            port=int(service_port),\n            workers=20,\n            reload=False,\n            log_config=None,\n        )\n        uvicorn_server = uvicorn.Server(uvicorn_config)\n        uvicorn_server.run()\n\n\ndef spark_link_app() -> FastAPI:\n    \"\"\"\n    Create Spark Link app.\n\n    Returns:\n        FastAPI: The configured FastAPI application instance","sourceCodeStart":103,"sourceCodeEnd":139,"githubUrl":"https://github.com/iflytek/astron-agent/blob/5e758547a83371a5a4b29dadf4ac03e8dd527635/core/plugin/link/app/start_server.py#L103-L139","documentation":"start_uvicorn reads the port from the environment via const.SERVICE_PORT_KEY and refuses to start the Uvicorn server if it is unset or empty, raising ValueError. This avoids uvicorn receiving port=None and gives an actionable message at startup.","triggerScenarios":"Calling start() / start_uvicorn() without SERVICE_PORT_KEY present in the environment — e.g. the service entrypoint is run with no exported port variable or an empty-string value.","commonSituations":"Launching the link service container without setting the port env var; renaming SERVICE_PORT_KEY's actual key name in config; running the app locally without loading the .env; empty value in deployment manifest causing the falsy check to fire.","solutions":["Set SERVICE_PORT_KEY (the env var name it maps to, e.g. SERVICE_PORT) to a numeric port like 8000 before starting the service","Load the service's .env file in the startup shell or container env (env_file in compose, env in k8s spec)","Confirm the const.SERVICE_PORT_KEY constant matches the variable actually defined in your environment","Optionally default the port in code (e.g. os.getenv(key, '8000')) if a default is acceptable"],"exampleFix":"// before\n$ python -m app.start_server\nValueError: SERVICE_PORT_KEY is not set\n// after\n$ export SERVICE_PORT=8080\n$ python -m app.start_server   # uvicorn starts on 0.0.0.0:8080","handlingStrategy":"validation","validationCode":"import os\nport = os.getenv('SERVICE_PORT')\nassert port and port.isdigit(), 'SERVICE_PORT must be set to a numeric port'","typeGuard":null,"tryCatchPattern":"try:\n    start()\nexcept ValueError as e:\n    logger.error('Startup aborted: %s — set SERVICE_PORT and retry', e)\n    sys.exit(1)","preventionTips":["Define SERVICE_PORT in the container/compose env_file","Give a sane default (e.g. 8000) when a default port is acceptable","Document required env vars in the service README","Verify required vars in an entrypoint pre-check script"],"tags":["config","env","uvicorn","startup"],"backgroundTag":"missing-env-var","analyzedSha":"5e758547a83371a5a4b29dadf4ac03e8dd527635","analyzedAt":"2026-09-12T08:03:51.356Z","contentChangedAt":"2026-09-12T08:03:51.356Z","schemaVersion":2},"datasetVersion":"2026-09-15T23:17:13.987Z"}