{"record":{"id":"fa556598f9c8c292","repo":"sgl-project/sglang","slug":"sidecar-requires-grpc-port-or-sglang-grpc-port","errorCode":null,"errorMessage":"--sidecar requires --grpc-port or SGLANG_GRPC_PORT.","messagePattern":"--sidecar requires --grpc-port or SGLANG_GRPC_PORT\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/sglang/srt/server_args.py","lineNumber":4529,"sourceCode":"        # Legacy takes precedence over grpc_port, keeping re-runs idempotent.\n        native_grpc = cfg.grpc_port is not None and not legacy_grpc\n        if cfg.sidecar_args is not None:\n            if cfg.sidecar is None:\n                raise ValueError(\"--sidecar-args requires --sidecar.\")\n            if not isinstance(cfg.sidecar_args, list) or not all(\n                isinstance(arg, str) for arg in cfg.sidecar_args\n            ):\n                raise ValueError(\"--sidecar-args must be a JSON array of strings.\")\n        if cfg.sidecar is not None:\n            if not cfg.sidecar.strip():\n                raise ValueError(\"--sidecar must not be empty.\")\n            if legacy_grpc:\n                raise ValueError(\n                    \"--sidecar requires SGLang's native gRPC server; \"\n                    \"it cannot be combined with --smg-grpc-mode/--grpc-mode.\"\n                )\n            if cfg.grpc_port is None:\n                raise ValueError(\"--sidecar requires --grpc-port or SGLANG_GRPC_PORT.\")\n        if native_grpc:\n            if cfg.use_ray:\n                raise ValueError(\n                    \"--grpc-port is not supported with --use-ray: the Ray \"\n                    \"serve launch path does not start the native gRPC server.\"\n                )\n            if cfg.encoder_only:\n                raise ValueError(\n                    \"--grpc-port is not supported with --encoder-only: \"\n                    \"encoder disaggregation uses its own server.\"\n                )\n            if cfg.tokenizer_worker_num > 1:\n                raise ValueError(\n                    \"Native gRPC does not yet support --tokenizer-worker-num > 1. \"\n                    \"Unset --grpc-port or set --tokenizer-worker-num 1.\"\n                )\n            if cfg.api_key or cfg.admin_api_key:\n                raise ValueError(","sourceCodeStart":4511,"sourceCodeEnd":4547,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/srt/server_args.py#L4511-L4547","documentation":"A sidecar only makes sense attached to the native gRPC listener, so --sidecar requires that a gRPC port be configured via --grpc-port or SGLANG_GRPC_PORT.","triggerScenarios":"Passing --sidecar without any --grpc-port flag and without SGLANG_GRPC_PORT in the environment.","commonSituations":"Assuming the sidecar attaches to the HTTP server; removing the gRPC port while keeping the sidecar during cleanup of a launch script.","solutions":["Add --grpc-port <port> (e.g. 50051)","Or export SGLANG_GRPC_PORT=<port>","Remove --sidecar if gRPC serving is not intended"],"exampleFix":"# before\n--sidecar \"python sidecar.py\"\n# after\n--grpc-port 50051 --sidecar \"python sidecar.py\"","handlingStrategy":"validation","validationCode":"import os\nif args.get(\"sidecar\") and not (args.get(\"grpc_port\") or os.environ.get(\"SGLANG_GRPC_PORT\")):\n    args[\"grpc_port\"] = 50051  # or fail fast","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Bundle sidecar settings into one config snippet that always includes --grpc-port","Document that --sidecar attaches to the gRPC server, not HTTP"],"tags":["grpc","sidecar","config-validation"],"backgroundTag":"dependent-option-missing","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T06:17:29.519Z"}