sgl-project/sglang · critical · RuntimeError

--sidecar requires importable module {module_name!r} with a

Error message

--sidecar requires importable module {module_name!r} with a main(argv) function.

What it means

Raised by SGLang's sidecar launcher when importlib.import_module() fails or the imported module has no `main` attribute. The --sidecar server argument expects a fully qualified, importable Python module exposing a main(argv) function, and this error means that contract was violated at process startup.

Source

Thrown at python/sglang/srt/entrypoints/sidecar.py:67

    parser = argparse.ArgumentParser(add_help=False, allow_abbrev=False)
    parser.add_argument(
        "--sidecar-shutdown-timeout",
        type=float,
        default=_DEFAULT_SIDECAR_SHUTDOWN_TIMEOUT,
    )
    parsed, provider_args = parser.parse_known_args(args or [])
    if parsed.sidecar_shutdown_timeout <= 0:
        raise ValueError("--sidecar-shutdown-timeout must be greater than 0.")
    return provider_args, parsed.sidecar_shutdown_timeout


def _run_sidecar(module_name: str, args: list[str], endpoint: str) -> None:
    kill_itself_when_parent_died()
    os.environ[SGLANG_GRPC_ENDPOINT_ENV] = endpoint
    try:
        main = getattr(importlib.import_module(module_name), "main")
    except (AttributeError, ImportError) as e:
        raise RuntimeError(
            f"--sidecar requires importable module {module_name!r} "
            "with a main(argv) function."
        ) from e

    if not callable(main):
        raise RuntimeError(
            f"--sidecar requires module {module_name!r} to expose "
            "a callable main(argv)."
        )

    main(args)


class Sidecar:
    def __init__(
        self,
        proc,
        module_name: str,

View on GitHub (pinned to 0132848349)

Solutions

1. Verify the module is importable in the server's environment: python -c "import mymodule; print(mymodule.main)"
2. Use a fully qualified dotted path (pkg.subpkg.sidecar_impl) rather than a file path
3. Ensure the module defines a top-level `def main(argv): ...` function
4. Install the sidecar module into the same virtualenv/conda env SGLang runs in

Example fix

# before
--sidecar my_sidcar_module
# after
--sidecar my_sidecar_module  # must define: def main(argv): ...

import importlib

def sidecar_ok(module_name: str) -> bool:
    try:
        mod = importlib.import_module(module_name)
    except Exception:
        return False
    return callable(getattr(mod, "main", None))

When it happens

Trigger: Launching the server with --sidecar some.module where some.module does not exist, is not on PYTHONPATH, has an import-time error (ImportError), or defines no `main` attribute (AttributeError).

Common situations: Typo in the module name, module installed in a different venv than the sglang server, module file not on sys.path (relative path instead of dotted module path), or the sidecar module renamed/removed in a version upgrade.

Related errors

• --sidecar requires module {module_name!r} to expose a callab
• Unknown serve backend {name!r}. Available values: {available
• Multiple distributions register serve backend {name!r}: {pro
• Failed to load serve backend {name!r} from {self._entry_poin
• Serve backend {name!r} factory returned {type(backend).__nam

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