unslothai/unsloth · error · ValueError

Helper LLM startup pre-cache must be true or false.

Error message

Helper LLM startup pre-cache must be true or false.

What it means

Raised by set_helper_precache_enabled when the value cannot be coerced to a boolean by _coerce_bool. The setting persists to the studio DB (upsert_app_settings) and gates an opt-in startup pre-cache thread for the Helper LLM; only unambiguously boolean-coercible input is accepted. The broad disable env var and explicit AI Assist calls bypass this gate entirely.

Source

Thrown at studio/backend/utils/helper_precache_settings.py:51

    """Read the persisted startup pre-cache preference.

    Missing or unreadable settings default to False so Unsloth startup never
    performs optional network work unless the user explicitly opted in.
    """
    try:
        from storage.studio_db import get_app_setting
        stored = get_app_setting(HELPER_PRECACHE_SETTING_KEY, None)
    except Exception:
        stored = None
    parsed = _coerce_bool(stored)
    return parsed if parsed is not None else DEFAULT_HELPER_PRECACHE_ENABLED


def set_helper_precache_enabled(value: Any) -> bool:
    """Persist whether Unsloth should pre-cache the Helper LLM at startup."""
    parsed = _coerce_bool(value)
    if parsed is None:
        raise ValueError("Helper LLM startup pre-cache must be true or false.")

    from storage.studio_db import upsert_app_settings

    upsert_app_settings({HELPER_PRECACHE_SETTING_KEY: parsed})
    return parsed


def should_preload_helper_on_startup() -> bool:
    """Gate the startup pre-cache thread.

    The persisted setting is opt-in and the existing broad disable env var wins.
    Explicit AI Assist calls do not use this gate; they remain user-triggered.
    """
    return get_helper_precache_enabled() and not helper_model_disabled_by_env()

View on GitHub (pinned to 203007d190)

Solutions

1. Pass a real boolean: set_helper_precache_enabled(True) / (False).
2. If the value comes from an env var or UI string, normalize it first (e.g. value in ('1','true','yes') → True).
3. Handle unset optional values before calling: if raw is None, skip the call rather than passing None.
4. Check _coerce_bool's accepted forms if you must send strings.

Example fix

# before
set_helper_precache_enabled(os.getenv("HELPER_PRECACHE"))  # None when unset -> ValueError

# after
raw = os.getenv("HELPER_PRECACHE")
if raw is not None:
    set_helper_precache_enabled(raw.lower() in ("1", "true", "yes"))

def to_bool_or_none(v):
    if isinstance(v, bool):
        return v
    if isinstance(v, (int, float)) and v in (0, 1):
        return bool(v)
    if isinstance(v, str) and v.strip().lower() in ("true", "1", "yes", "false", "0", "no"):
        return v.strip().lower() in ("true", "1", "yes")
    return None

# guard: parsed = to_bool_or_none(raw); assert parsed is not None

def is_coercible_bool(value) -> bool:
    if isinstance(value, bool):
        return True
    if isinstance(value, int):
        return value in (0, 1)
    if isinstance(value, str):
        return value.strip().lower() in ("true", "false", "1", "0", "yes", "no")
    return False

When it happens

Trigger: Calling set_helper_precache_enabled with values _coerce_bool rejects — e.g. 'maybe', 2, [], None, or 'on'/'off' depending on the coercion rules — rather than True/False, 1/0, or 'true'/'false'.

Common situations: Settings UI posting a checkbox tri-state or raw string; API clients sending JSON numbers other than 0/1; scripts passing os.getenv(...) raw (None when the var is unset).

Related errors

• Embedding model must be a Hugging Face repo id (e.g. 'unslot
• 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.
• Auto-unload API-loaded only must be true or false.

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