{"record":{"id":"714e0af49e5cb8bb","repo":"unslothai/unsloth","slug":"unsloth-mlx-use-adapter-must-be-none-true-false","errorCode":null,"errorMessage":"Unsloth MLX: use_adapter must be None, True, False, or a string.","messagePattern":"Unsloth MLX: use_adapter must be None, True, False, or a string\\.","errorType":"validation","errorClass":"TypeError","httpStatus":null,"severity":"error","filePath":"studio/backend/core/inference/mlx_inference.py","lineNumber":60,"sourceCode":"            unsupported.append(path)\n        else:\n            adapters.append((path, module, base))\n    return adapters, unsupported\n\n\n@contextmanager\ndef _temporary_mlx_adapter_state(model, use_adapter):\n    \"\"\"Select base or adapter modules for one request, then restore the tree.\"\"\"\n    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","sourceCodeStart":42,"sourceCodeEnd":78,"githubUrl":"https://github.com/unslothai/unsloth/blob/203007d19051dcd2ae33876786d117c99f6b0368/studio/backend/core/inference/mlx_inference.py#L42-L78","documentation":"Thrown by _temporary_mlx_adapter_state in the MLX inference backend when the use_adapter argument is not one of the accepted values. The contextmanager routes a single request through the LoRA adapter or the base model, so it first validates use_adapter: None (keep current state), True (adapter), False (base), or a string (named adapter, which raises NotImplementedError instead). Anything else (e.g. an int, dict, or numpy bool) fails this TypeError before any adapter tree surgery happens.","triggerScenarios":"Calling the MLX generation/streaming API with use_adapter set to a non-boolean, non-None, non-string value — e.g. use_adapter=1, use_adapter=np.True_, use_adapter={'name': 'my-lora'}, or a value parsed from JSON that arrived as a number. The check fires immediately upon entering the context manager, before any model work.","commonSituations":"JSON request payloads where the client sent use_adapter: 1 instead of true; passing numpy/torch booleans from a training pipeline into the inference API; a config schema that defaults use_adapter to 0/''.","solutions":["Pass a strict Python bool: use_adapter=True to use the loaded adapter, use_adapter=False for the base model, or use_adapter=None to keep the current state.","If the value comes from JSON/API input, coerce or validate it at the request boundary (bool(value) is not enough — explicitly accept only true/false/null/strings).","If you meant to select an adapter by name, note strings raise NotImplementedError; load the desired adapter as the active model instead."],"exampleFix":"# before\nbackend.stream_response(messages, use_adapter=1)\n\n# after\nbackend.stream_response(messages, use_adapter=True)","handlingStrategy":"type-guard","validationCode":"def is_valid_use_adapter(v) -> bool:\n    return v is None or isinstance(v, bool) or isinstance(v, str)","typeGuard":"def is_use_adapter(value: object) -> TypeGuard[None | bool | str]:\n    return value is None or isinstance(value, bool) or isinstance(value, str)","tryCatchPattern":"try:\n    with _temporary_mlx_adapter_state(model, use_adapter):\n        generate()\nexcept TypeError as e:\n    if 'use_adapter' in str(e):\n        raise ValueError(f'bad use_adapter={use_adapter!r}') from e\n    raise","preventionTips":["Validate use_adapter at the API boundary: reject anything that is not null/true/false/string with a 400.","Never pass numpy/torch booleans through; normalize with `v is True or v is False` style checks, not bool(v).","Note that string values hit NotImplementedError — route named-adapter requests to adapter loading instead."],"tags":["mlx","lora","type-validation","inference"],"backgroundTag":null,"analyzedSha":"203007d19051dcd2ae33876786d117c99f6b0368","analyzedAt":"2026-08-15T02:48:39.846Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}