unslothai/unsloth · error · SystemExit

Error: Invalid UNSLOTH_CPU_THREADS value {_raw!r}: {exc}

Error message

Error: Invalid UNSLOTH_CPU_THREADS value {_raw!r}: {exc}

What it means

Raised at backend startup (import time in main.py) when utils.cpu_threads.configure_cpu_threads() raises ValueError while parsing the UNSLOTH_CPU_THREADS environment variable. It terminates the process via SystemExit with the raw value echoed, because an unparseable thread cap would otherwise silently degrade performance or oversubscribe CPUs.

Source

Thrown at studio/backend/main.py:194

# Backend dir on sys.path so _platform_compat imports under `uvicorn main:app`.
_backend_dir = str(_Path(__file__).parent)
if _backend_dir not in sys.path:
    sys.path.insert(0, _backend_dir)

# OS trust store for TLS before anything opens a connection: behind a
# TLS-inspecting proxy certifi alone rejects every Hub request.
from utils.native_tls import activate_native_tls

activate_native_tls()

# `uvicorn main:app` bypasses run.py; seed thread caps here too.
from utils.cpu_threads import configure_cpu_threads

try:
    configure_cpu_threads()
except ValueError as exc:
    _raw = os.environ.get("UNSLOTH_CPU_THREADS")
    raise SystemExit(f"Error: Invalid UNSLOTH_CPU_THREADS value {_raw!r}: {exc}") from None

# Anaconda/conda-forge Python: seed platform._sys_version_cache before attrs -> rich ->
# structlog -> platform crashes. See https://github.com/python/cpython/issues/102396
import _platform_compat  # noqa: F401

# Direct `uvicorn main:app` bypasses run.py, so re-export here too. Required BEFORE the
# unsloth-zoo import below, whose LLAMA_CPP_DEFAULT_DIR binding is import-time.
from utils.paths.storage_roots import studio_root as _studio_root

# Same reason, same deadline: unsloth_zoo.compiler reads UNSLOTH_COMPILE_LOCATION
# at import time, and without this a direct start falls back to a CWD-relative
# unsloth_compiled_cache (on Windows that is the user profile).
from utils.paths.storage_roots import setup_cache_env as _setup_cache_env

try:
    _setup_cache_env()
except Exception:  # noqa: BLE001
    pass

View on GitHub (pinned to 203007d190)

Solutions

1. Inspect the echoed raw value in the error message and set UNSLOTH_CPU_THREADS to a positive integer (e.g. '8') or unset it entirely to use auto-detection.
2. If set in docker-compose/Kubernetes, check the deployment manifests for an empty or interpolated value and correct it.
3. After fixing, restart the backend; the process exits before serving so no stale state exists.

Example fix

# before
export UNSLOTH_CPU_THREADS=  # empty -> SystemExit
# after
unset UNSLOTH_CPU_THREADS        # auto-detect
# or
export UNSLOTH_CPU_THREADS=8

import os

def cpu_threads_env_valid() -> bool:
    raw = os.environ.get("UNSLOTH_CPU_THREADS")
    if raw is None:
        return True  # auto-detect
    try:
        n = int(raw)
    except ValueError:
        return False
    return n >= 1

When it happens

Trigger: Starting the studio backend (directly via 'uvicorn main:app' or through run.py) with UNSLOTH_CPU_THREADS set to a non-integer such as 'auto', '4.5', an empty string, or a value like '0'/'-1' that configure_cpu_threads rejects.

Common situations: Copying a docker-compose/k8s env block where the variable was templated to empty ('UNSLOTH_CPU_THREADS='), quoting mistakes in shell exports, or a version change that tightened accepted values (e.g. now requiring a positive integer).

Related errors

• UNSLOTH_STUDIO_MCP_TOKEN is required when MCP is enabled
• Error: Invalid UNSLOTH_CPU_THREADS value {configured!r}: {ex
• Unknown audio_type: {audio_type}
• Unsloth: distributed MLX inference requires parallel_mode='p
• sd-server failed to become ready. Last output: {tail[:2000]}

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