sgl-project/sglang · error · ValueError

--sidecar must not be empty.

Error message

--sidecar must not be empty.

What it means

--sidecar accepts a command string to run alongside SGLang's native gRPC server; an empty or whitespace-only string is rejected because there is no command to execute.

Source

Thrown at python/sglang/srt/server_args.py:4522

            if cfg.grpc_worker_threads is not None and cfg.grpc_worker_threads < 1:
                raise ValueError(
                    "SGLANG_GRPC_WORKER_THREADS "
                    f"({cfg.grpc_worker_threads}) must be >= 1"
                )

        # Native gRPC is incompatible with launch paths it doesn't wire into.
        # Legacy takes precedence over grpc_port, keeping re-runs idempotent.
        native_grpc = cfg.grpc_port is not None and not legacy_grpc
        if cfg.sidecar_args is not None:
            if cfg.sidecar is None:
                raise ValueError("--sidecar-args requires --sidecar.")
            if not isinstance(cfg.sidecar_args, list) or not all(
                isinstance(arg, str) for arg in cfg.sidecar_args
            ):
                raise ValueError("--sidecar-args must be a JSON array of strings.")
        if cfg.sidecar is not None:
            if not cfg.sidecar.strip():
                raise ValueError("--sidecar must not be empty.")
            if legacy_grpc:
                raise ValueError(
                    "--sidecar requires SGLang's native gRPC server; "
                    "it cannot be combined with --smg-grpc-mode/--grpc-mode."
                )
            if cfg.grpc_port is None:
                raise ValueError("--sidecar requires --grpc-port or SGLANG_GRPC_PORT.")
        if native_grpc:
            if cfg.use_ray:
                raise ValueError(
                    "--grpc-port is not supported with --use-ray: the Ray "
                    "serve launch path does not start the native gRPC server."
                )
            if cfg.encoder_only:
                raise ValueError(
                    "--grpc-port is not supported with --encoder-only: "
                    "encoder disaggregation uses its own server."
                )

View on GitHub (pinned to 0132848349)

Solutions

1. Remove the --sidecar flag entirely if no sidecar is wanted
2. Set a real command: --sidecar "python sidecar.py"
3. Check that the shell variable used for --sidecar is non-empty before launching

Example fix

# before
--sidecar ""
# after
--sidecar "python sidecar.py"

if args.get("sidecar") is not None and not args["sidecar"].strip():
    args.pop("sidecar")  # or fail fast with a clear message

When it happens

Trigger: Passing --sidecar "" or --sidecar " " (e.g. from an unset shell variable like --sidecar "$SIDECAR_CMD").

Common situations: Templated launch scripts where the sidecar variable is empty in some environments; disabling the sidecar by setting it to an empty string instead of removing the flag.

Related errors

• --sidecar-args requires --sidecar.
• --sidecar-args must be a JSON array of strings.
• --sidecar requires SGLang's native gRPC server; it cannot be
• --sidecar requires --grpc-port or SGLANG_GRPC_PORT.
• SGLANG_GRPC_WORKER_THREADS ({cfg.grpc_worker_threads}) must

AI-assisted analysis of sgl-project/sglang@0132848349 (2026-08-28). Data as JSON: /api/errors/ee3f375306671b6a. Report an issue: GitHub.