{"record":{"id":"8a24a7fe3abbd381","repo":"sgl-project/sglang","slug":"sidecar-requires-importable-module-module-name","errorCode":null,"errorMessage":"--sidecar requires importable module {module_name!r} with a main(argv) function.","messagePattern":"--sidecar requires importable module (.+?) with a main\\(argv\\) function\\.","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"critical","filePath":"python/sglang/srt/entrypoints/sidecar.py","lineNumber":67,"sourceCode":"    parser = argparse.ArgumentParser(add_help=False, allow_abbrev=False)\n    parser.add_argument(\n        \"--sidecar-shutdown-timeout\",\n        type=float,\n        default=_DEFAULT_SIDECAR_SHUTDOWN_TIMEOUT,\n    )\n    parsed, provider_args = parser.parse_known_args(args or [])\n    if parsed.sidecar_shutdown_timeout <= 0:\n        raise ValueError(\"--sidecar-shutdown-timeout must be greater than 0.\")\n    return provider_args, parsed.sidecar_shutdown_timeout\n\n\ndef _run_sidecar(module_name: str, args: list[str], endpoint: str) -> None:\n    kill_itself_when_parent_died()\n    os.environ[SGLANG_GRPC_ENDPOINT_ENV] = endpoint\n    try:\n        main = getattr(importlib.import_module(module_name), \"main\")\n    except (AttributeError, ImportError) as e:\n        raise RuntimeError(\n            f\"--sidecar requires importable module {module_name!r} \"\n            \"with a main(argv) function.\"\n        ) from e\n\n    if not callable(main):\n        raise RuntimeError(\n            f\"--sidecar requires module {module_name!r} to expose \"\n            \"a callable main(argv).\"\n        )\n\n    main(args)\n\n\nclass Sidecar:\n    def __init__(\n        self,\n        proc,\n        module_name: str,","sourceCodeStart":49,"sourceCodeEnd":85,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/srt/entrypoints/sidecar.py#L49-L85","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","solutions":["Verify the module is importable in the server's environment: python -c \"import mymodule; print(mymodule.main)\"","Use a fully qualified dotted path (pkg.subpkg.sidecar_impl) rather than a file path","Ensure the module defines a top-level `def main(argv): ...` function","Install the sidecar module into the same virtualenv/conda env SGLang runs in"],"exampleFix":"# before\n--sidecar my_sidcar_module\n# after\n--sidecar my_sidecar_module  # must define: def main(argv): ...","handlingStrategy":"validation","validationCode":"import importlib\n\ndef sidecar_ok(module_name: str) -> bool:\n    try:\n        mod = importlib.import_module(module_name)\n    except Exception:\n        return False\n    return callable(getattr(mod, \"main\", None))","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Smoke-test `importlib.import_module(name)` + hasattr(main) in a preflight check before passing --sidecar","Keep sidecar modules in the same environment/PYTHONPATH as the sglang server"],"tags":["sidecar","module-import","startup","sglang","cli"],"backgroundTag":"module-not-importable","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T06:17:29.519Z"}