unslothai/unsloth · error · ValueError

Auto-unload API-loaded only must be true or false.

Error message

Auto-unload API-loaded only must be true or false.

What it means

Raised by set_openai_auto_switch in openai_auto_switch_settings.py:324-327 when api_only is provided and _coerce_bool fails. Accepted inputs are exactly True/False or the strings 1/true/yes/on and 0/false/no/off; ints, floats, and any other string raise this error. api_only restricts auto-unload to API-loaded models.

Source

Thrown at studio/backend/utils/openai_auto_switch_settings.py:326

            raise ValueError(
                f"Media auto-unload idle seconds must be 0 (off) or at least "
                f"{MIN_AUTO_UNLOAD_IDLE_SECONDS}."
            )
    parsed_keep_kv = None
    if keep_kv is not None:
        parsed_keep_kv = _coerce_bool(keep_kv)
        if parsed_keep_kv is None:
            raise ValueError("Keep KV on idle unload must be true or false.")
    parsed_auto_download = None
    if auto_download is not None:
        parsed_auto_download = _coerce_bool(auto_download)
        if parsed_auto_download is None:
            raise ValueError("Auto-download missing models must be true or false.")
    parsed_api_only = None
    if api_only is not None:
        parsed_api_only = _coerce_bool(api_only)
        if parsed_api_only is None:
            raise ValueError("Auto-unload API-loaded only must be true or false.")
    from storage.studio_db import upsert_app_settings

    updates: dict[str, Any] = {OPENAI_AUTO_SWITCH_SETTING_KEY: parsed_enabled}
    if parsed_idle is not None:
        updates[AUTO_UNLOAD_IDLE_SETTING_KEY] = parsed_idle
    if parsed_media_idle is not None:
        updates[MEDIA_AUTO_UNLOAD_IDLE_SETTING_KEY] = parsed_media_idle
    if parsed_keep_kv is not None:
        updates[AUTO_UNLOAD_KEEP_KV_SETTING_KEY] = parsed_keep_kv
    if parsed_auto_download is not None:
        updates[OPENAI_AUTO_DOWNLOAD_SETTING_KEY] = parsed_auto_download
    if parsed_api_only is not None:
        updates[AUTO_UNLOAD_API_ONLY_SETTING_KEY] = parsed_api_only
    upsert_app_settings(updates)
    _invalidate(OPENAI_AUTO_SWITCH_SETTING_KEY)
    if parsed_idle is not None:
        _invalidate(AUTO_UNLOAD_IDLE_SETTING_KEY)
    if parsed_media_idle is not None:

View on GitHub (pinned to 203007d190)

Solutions

1. Convert to bool before calling: bool flag from your own checkbox handling
2. Use one of the accepted string tokens if strings are unavoidable
3. Send native JSON booleans from the API client
4. Leave the argument out to preserve the stored setting

Example fix

# before
set_openai_auto_switch(enabled=True, api_only=1)

# after
set_openai_auto_switch(enabled=True, api_only=True)

def to_bool(v) -> bool | None:
    if isinstance(v, bool):
        return v
    if isinstance(v, str):
        n = v.strip().lower()
        if n in {"1", "true", "yes", "on"}: return True
        if n in {"0", "false", "no", "off"}: return False
    return None

if api_only is not None and to_bool(api_only) is None:
    raise HTTPException(400, "api_only must be a boolean")

def is_bool_like(v: object) -> bool:
    return isinstance(v, bool) or (
        isinstance(v, str) and v.strip().lower() in {"1","true","yes","on","0","false","no","off"}
    )

try:
    set_openai_auto_switch(enabled=True, api_only=api_only)
except ValueError as exc:
    raise HTTPException(400, str(exc)) from exc

When it happens

Trigger: set_openai_auto_switch(enabled=True, api_only=1) (int), api_only="only", api_only="api". Python None skips the field entirely.

Common situations: REST payloads where the toggle was serialized as an int; query parameters parsed to ints; scripts passing flags like "yes!".

Related errors

• Helper LLM startup pre-cache must be true or false.
• OpenAI auto-switch must be true or false.
• Keep KV on idle unload must be true or false.
• Auto-download missing models must be true or false.
• Public preview sharing must be true or false.

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