sgl-project/sglang · critical · RuntimeError

Failed to load customized {component_name}; native fallback

Error message

Failed to load customized {component_name}; native fallback is disabled for this component configuration.

What it means

load() attempts the customized loader first; if it raises and should_raise_customized_load_error() says native fallback is disabled for this configuration, the original exception is printed and re-raised wrapped as RuntimeError with this message (native_loader_required exceptions are re-raised unchanged).

Source

Thrown at python/sglang/multimodal_gen/runtime/loader/component_loaders/component_loader.py:282

        try:
            component = self._load_customized_with_context(
                component_model_path,
                server_args,
                component_name,
                attn_backend,
                component_attn_name,
                self.allow_global_attention_backend_fallback,
            )
            source = "sgl-diffusion"
        except (ComponentCheckpointUnsupportedError, ComponentResidencyError):
            raise
        except Exception as e:
            native_loader_required = isinstance(e, NativeComponentLoaderRequired)
            if self.should_raise_customized_load_error(server_args, component_name):
                if native_loader_required:
                    raise
                traceback.print_exc()
                raise RuntimeError(
                    f"Failed to load customized {component_name}; native fallback "
                    "is disabled for this component configuration."
                ) from e
            if native_loader_required:
                logger.info("%s", e)
            elif "Unsupported model architecture" in str(e):
                logger.info(
                    f"Component: {component_name} doesn't have a customized version yet, using native version"
                )
            else:
                traceback.print_exc()
                logger.error(
                    f"Error while loading customized {component_name}, falling back to native version"
                )
            # fallback to native version
            component = self._load_native_with_context(
                component_model_path,
                server_args,

View on GitHub (pinned to 0132848349)

Solutions

1. Read the printed traceback above the RuntimeError — the root cause is the actual load failure; fix that first (missing files, bad config keys, dtype issues)
2. Verify the component directory, config.json, and weight files are complete and match the model revision
3. If fallback is acceptable, remove the server-arg settings (e.g. component_quantizations/precision overrides) that disabled native fallback

try:
    loader.load(component_model_path, server_args, name)
except RuntimeError as e:
    if "native fallback is disabled" in str(e):
        # root cause is in __cause__; inspect before retrying
        log.exception("customized load failed", exc_info=e.__cause__)
    raise

When it happens

Trigger: The customized load path throws any non-NativeComponentLoaderRequired exception while the component's policy forbids falling back to the native transformers/diffusers loader (e.g. quantization or precision settings that make fallback unsafe).

Common situations: A corrupted or misconfigured component checkpoint combined with server args that disable fallback (e.g. explicit precision/quantization for the component); customized loader bugs for newly added components.

Related errors

• Z-Image transformer has no `rotary_emb`. It likely loaded vi
• f"Cannot parse checkpoint quantization for {component_name!r
• f"Transformers-managed {component_name!r} quantization requi
• {component_name!r} does not support an explicit quantization
• Cannot parse checkpoint quantization metadata for {component

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