{"record":{"id":"ade5ae89195e4eb3","repo":"sgl-project/sglang","slug":"sidecar-requires-sglang-s-native-grpc-server-it","errorCode":null,"errorMessage":"--sidecar requires SGLang's native gRPC server; it cannot be combined with --smg-grpc-mode/--grpc-mode.","messagePattern":"--sidecar requires SGLang's native gRPC server; it cannot be combined with --smg-grpc-mode/--grpc-mode\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/sglang/srt/server_args.py","lineNumber":4524,"sourceCode":"                    \"SGLANG_GRPC_WORKER_THREADS \"\n                    f\"({cfg.grpc_worker_threads}) must be >= 1\"\n                )\n\n        # Native gRPC is incompatible with launch paths it doesn't wire into.\n        # 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(","sourceCodeStart":4506,"sourceCodeEnd":4542,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/srt/server_args.py#L4506-L4542","documentation":"The --sidecar feature is wired into SGLang's native gRPC server only; it cannot be used with the legacy gRPC mode flags (--smg-grpc-mode / --grpc-mode), whose launch path never starts a sidecar.","triggerScenarios":"Passing both --grpc-mode (or --smg-grpc-mode) and --sidecar in the same ServerArgs.","commonSituations":"Migrating an old deployment from legacy grpc mode to native gRPC and leaving the old mode flag in the command line; combining flags from two different docs pages.","solutions":["Remove --grpc-mode / --smg-grpc-mode and use native gRPC via --grpc-port","Or drop --sidecar if legacy grpc mode is required"],"exampleFix":"# before\n--grpc-mode --sidecar \"python sidecar.py\"\n# after\n--grpc-port 50051 --sidecar \"python sidecar.py\"","handlingStrategy":"validation","validationCode":"legacy = args.get(\"grpc_mode\") or args.get(\"smg_grpc_mode\")\nif legacy and args.get(\"sidecar\"):\n    raise SystemExit(\"sidecar requires native gRPC (--grpc-port); remove --grpc-mode/--smg-grpc-mode\")","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Treat legacy gRPC mode and native gRPC as an either/or choice enforced by a single config variable","When migrating, grep launch scripts for both new and old flag names"],"tags":["grpc","sidecar","flag-conflict","config-validation"],"backgroundTag":"mutually-exclusive-options","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T06:17:29.519Z"}