{"record":{"id":"08476120cb4bb681","repo":"unslothai/unsloth","slug":"unsloth-mlx-cannot-disable-adapter-layers-without","errorCode":null,"errorMessage":"Unsloth MLX: cannot disable adapter layers without their base modules: {unsupported[:5] joined by ', '}","messagePattern":"Unsloth MLX: cannot disable adapter layers without their base modules: (.+?)","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"studio/backend/core/inference/mlx_inference.py","lineNumber":69,"sourceCode":"    if use_adapter is None:\n        yield\n        return\n    if isinstance(use_adapter, str):\n        raise NotImplementedError(\n            \"Unsloth MLX: named adapter selection is not supported; use True for \"\n            \"the loaded adapter or False for the base model.\"\n        )\n    if use_adapter is not True and use_adapter is not False:\n        raise TypeError(\"Unsloth MLX: use_adapter must be None, True, False, or a string.\")\n\n    adapters, unsupported = _mlx_adapter_modules(model)\n    if use_adapter is True:\n        if not adapters and not unsupported:\n            logger.warning(\"MLX adapter requested, but the active model has no adapter layers\")\n        yield\n        return\n    if unsupported:\n        raise RuntimeError(\n            \"Unsloth MLX: cannot disable adapter layers without their base modules: \"\n            + \", \".join(unsupported[:5])\n        )\n    if not adapters:\n        yield\n        return\n\n    from mlx.utils import tree_unflatten\n\n    base_modules = tree_unflatten([(path, base) for path, _, base in adapters])\n    adapter_modules = tree_unflatten([(path, wrapper) for path, wrapper, _ in adapters])\n    try:\n        model.update_modules(base_modules)\n        yield\n    finally:\n        model.update_modules(adapter_modules)\n\n","sourceCodeStart":51,"sourceCodeEnd":87,"githubUrl":"https://github.com/unslothai/unsloth/blob/203007d19051dcd2ae33876786d117c99f6b0368/studio/backend/core/inference/mlx_inference.py#L51-L87","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Serve the adapter (use_adapter=True or None) instead of trying to disable it.","Re-merge the adapter into the base model with unsloth/export tooling and load the merged checkpoint — then no adapter swap is needed.","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."],"exampleFix":"# before\nwith _temporary_mlx_adapter_state(model, use_adapter=False):\n    generate(...)  # raises: base modules missing\n\n# after\n# merge adapter into base, load merged model\nmodel = load_model('me/model-lora-merged')\nwith _temporary_mlx_adapter_state(model, use_adapter=None):\n    generate(...)","handlingStrategy":"validation","validationCode":"adapters, unsupported = _mlx_adapter_modules(model)\nif use_adapter is False and unsupported:\n    raise ValueError(f'base modules missing for: {unsupported[:5]}')  # fail before dispatch","typeGuard":null,"tryCatchPattern":"try:\n    with _temporary_mlx_adapter_state(model, use_adapter=False):\n        generate()\nexcept RuntimeError as e:\n    if 'cannot disable adapter layers' in str(e):\n        # fall back to serving the adapter as-is\n        generate_with_adapter()","preventionTips":["Before advertising base-model mode, probe the loaded model with _mlx_adapter_modules and mark base-mode unavailable when unsupported is non-empty.","Prefer merged checkpoints when you need guaranteed base-model serving.","Surface the offending module paths in UI/API so users know which layers block disabling."],"tags":["mlx","lora","model-architecture","inference"],"backgroundTag":null,"analyzedSha":"203007d19051dcd2ae33876786d117c99f6b0368","analyzedAt":"2026-08-15T02:48:39.846Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}