unslothai/unsloth · error · RuntimeError

Unsloth MLX: cannot disable adapter layers without their bas

Error message

Unsloth MLX: cannot disable adapter layers without their base modules: {unsupported[:5] joined by ', '}

What it means

Raised when use_adapter=False is requested (serve the base model) but the loaded model has LoRA adapter layers whose underlying base modules cannot be found. Disabling adapters works by swapping each adapter wrapper back to its base module via _mlx_adapter_modules; if a wrapper reports no base module (path listed in `unsupported`), the swap would silently drop layers, so the backend refuses. The message lists up to five offending module paths.

Source

Thrown at studio/backend/core/inference/mlx_inference.py:69

    if use_adapter is None:
        yield
        return
    if isinstance(use_adapter, str):
        raise NotImplementedError(
            "Unsloth MLX: named adapter selection is not supported; use True for "
            "the loaded adapter or False for the base model."
        )
    if use_adapter is not True and use_adapter is not False:
        raise TypeError("Unsloth MLX: use_adapter must be None, True, False, or a string.")

    adapters, unsupported = _mlx_adapter_modules(model)
    if use_adapter is True:
        if not adapters and not unsupported:
            logger.warning("MLX adapter requested, but the active model has no adapter layers")
        yield
        return
    if unsupported:
        raise RuntimeError(
            "Unsloth MLX: cannot disable adapter layers without their base modules: "
            + ", ".join(unsupported[:5])
        )
    if not adapters:
        yield
        return

    from mlx.utils import tree_unflatten

    base_modules = tree_unflatten([(path, base) for path, _, base in adapters])
    adapter_modules = tree_unflatten([(path, wrapper) for path, wrapper, _ in adapters])
    try:
        model.update_modules(base_modules)
        yield
    finally:
        model.update_modules(adapter_modules)

View on GitHub (pinned to 203007d190)

Solutions

1. Serve the adapter (use_adapter=True or None) instead of trying to disable it.
2. Re-merge the adapter into the base model with unsloth/export tooling and load the merged checkpoint — then no adapter swap is needed.
3. Inspect the module paths in the error message against the model config to identify which layers lost their base modules, and re-export the model with those layers intact.

Example fix

# before
with _temporary_mlx_adapter_state(model, use_adapter=False):
    generate(...)  # raises: base modules missing

# after
# merge adapter into base, load merged model
model = load_model('me/model-lora-merged')
with _temporary_mlx_adapter_state(model, use_adapter=None):
    generate(...)

adapters, unsupported = _mlx_adapter_modules(model)
if use_adapter is False and unsupported:
    raise ValueError(f'base modules missing for: {unsupported[:5]}')  # fail before dispatch

try:
    with _temporary_mlx_adapter_state(model, use_adapter=False):
        generate()
except RuntimeError as e:
    if 'cannot disable adapter layers' in str(e):
        # fall back to serving the adapter as-is
        generate_with_adapter()

When it happens

Trigger: Loading a LoRA-merged or adapter-wrapped MLX model whose adapter layers lack base modules (e.g. an adapter applied to modules that were never loaded, or a partially-merged checkpoint), then issuing a request with use_adapter=False or otherwise entering the context manager with False.

Common situations: Manually merged adapters where base projections were pruned; quantized adapter checkpoints that dropped base layers; experimenting with adapter-swap tooling on an unsupported architecture; testing 'base vs adapter' comparison on a model that was saved adapter-only.

Related errors

• Unsloth MLX: use_adapter must be None, True, False, or a str
• Unsloth: distributed MLX inference for LoRA adapter repos is
• No model loaded
• apply_chat_template returned None — tokenizer may be incompa
• The requested LoRA adapters could not be applied: baking ada

AI-assisted analysis of unslothai/unsloth@203007d190 (2026-08-15). Data as JSON: /api/errors/08476120cb4bb681. Report an issue: GitHub.