sgl-project/sglang · error · ModuleNotFoundError

{crate.python_module} is not bundled or cached, and Rust ext

Error message

{crate.python_module} is not bundled or cached, and Rust extension build mode is 'never'

What it means

ModuleNotFoundError raised when build mode is 'never', the extension is neither bundled with the wheel nor present in the on-disk cache, and building is forbidden. This is the explicit, controlled outcome of choosing 'never' in an environment lacking prebuilt artifacts (common in hermetic/air-gapped deployments).

Source

Thrown at python/sglang/srt/rust_extensions/loader.py:117

            "start a new Python process"
        )

    if workspace is None:
        workspace = _RUST_WORKSPACE
    crate = _discover_crate(workspace, python_module)
    context = _build_context(crate)
    cache_root = _cache_root(cache_dir)
    extension_path = _cached_extension_path(cache_root, crate, context.fingerprint)
    lock_path = (
        cache_root / "locks" / f"{crate.package}-{context.target_fingerprint}.lock"
    )

    with _filesystem_lock(lock_path):
        if mode != "force" and extension_path.is_file():
            return _load_extension_from_path(crate.python_module, extension_path)

        if mode == "never":
            raise ModuleNotFoundError(
                f"{crate.python_module} is not bundled or cached, and Rust extension "
                "build mode is 'never'",
                name=crate.python_module,
            )

        target_dir = cache_root / "targets" / context.target_fingerprint
        artifact = _cargo_build(crate, target_dir)
        if _source_digest(crate.workspace) != context.source_digest:
            raise RuntimeError(
                f"Rust sources under {crate.workspace} changed during the build; "
                "the result was not cached"
            )
        _stage_atomically(artifact, extension_path)
        return _load_extension_from_path(crate.python_module, extension_path)


def _import_bundled_extension(module_name: str) -> ModuleType | None:
    try:

View on GitHub (pinned to 0132848349)

Solutions

Pre-build the extension once with mode auto or force (or run the repo's build step) so the cache is populated, then use never
Install a wheel that bundles the extension
If building is acceptable in your environment, switch SGLANG_RUST_BUILD_MODE to auto

Example fix

# before
export SGLANG_RUST_BUILD_MODE=never  # source checkout, no cache -> ModuleNotFoundError
# after
python -c "from sglang.srt.rust_extensions.loader import load_rust_extension; load_rust_extension(CRATE, mode='force')"
export SGLANG_RUST_BUILD_MODE=never

Defensive patterns

Strategy: validation

Validate before calling

from sglang.srt.rust_extensions.loader import load_rust_extension
try:
    mod = load_rust_extension(crate, mode="never")
except ModuleNotFoundError:
    raise RuntimeError("prebuild the extension (mode auto/force) before using 'never'")

Prevention

Pre-build extensions during image build so 'never' mode never needs Cargo
Install wheels that bundle the Rust extensions in hermetic environments
Verify the extension cache directory is populated before enabling 'never' mode

When it happens

Trigger: Setting SGLANG_RUST_BUILD_MODE=never (or passing mode="never") on a source checkout without a prior build, or on a wheel that does not bundle the crate; after wiping the extension cache directory so extension_path.is_file() is False.

Common situations: Security/hermetic environments that forbid invoking Cargo; CI images built without the Rust extensions; accidentally enabling 'never' locally while developing from source.

Related errors

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