unslothai/unsloth · error · ValueError

UNSLOTH_CPU_THREADS must be a positive integer

Error message

UNSLOTH_CPU_THREADS must be a positive integer

What it means

Raised while parsing the UNSLOTH_CPU_THREADS environment variable: the value could not be parsed with int(). The helper runs before OpenMP/BLAS-using libraries are imported and fans the single value out to all thread-pool env vars (OMP_NUM_THREADS etc.) via setdefault, so it must be a clean positive integer literal. The original ValueError from int() is chained as the cause.

Source

Thrown at studio/backend/utils/cpu_threads.py:33

)


def configure_cpu_threads(env: Optional[MutableMapping[str, str]] = None) -> None:
    """Apply ``UNSLOTH_CPU_THREADS`` to native CPU pools when configured.

    Must run before importing libraries that initialize an OpenMP or BLAS
    pool. Library-specific vars are left untouched so users can override a
    single runtime independently.
    """
    environ = os.environ if env is None else env
    configured = environ.get("UNSLOTH_CPU_THREADS", "").strip()
    if not configured:
        return

    try:
        thread_count = int(configured)
    except ValueError as exc:
        raise ValueError("UNSLOTH_CPU_THREADS must be a positive integer") from exc
    if thread_count < 1:
        raise ValueError("UNSLOTH_CPU_THREADS must be a positive integer")

    value = str(thread_count)
    for variable in _THREAD_POOL_ENV_VARS:
        environ.setdefault(variable, value)

View on GitHub (pinned to 203007d190)

Solutions

1. Set the variable to a bare positive integer: UNSLOTH_CPU_THREADS=8
2. Check for quoting/parsing issues in .env, docker-compose, or Helm values (e.g. 8.0 vs 8)
3. Unset the variable entirely if you want library defaults — the helper returns silently when it is empty

Example fix

# before (docker-compose)
environment:
  - UNSLOTH_CPU_THREADS=8.0   # int('8.0') raises

# after
environment:
  - UNSLOTH_CPU_THREADS=8

import os

def validate_cpu_threads_env(env=None) -> int | None:
    env = env or os.environ
    raw = env.get("UNSLOTH_CPU_THREADS", "").strip()
    if not raw:
        return None
    try:
        n = int(raw)
    except ValueError:
        raise ValueError(f"UNSLOTH_CPU_THREADS={raw!r} is not an integer")
    if n < 1:
        raise ValueError(f"UNSLOTH_CPU_THREADS={raw!r} must be >= 1")
    return n

When it happens

Trigger: UNSLOTH_CPU_THREADS="8 cores", "8.0", "", padding like " 8 " is fine (stripped) but "8,4" or any non-numeric string hits int() and raises. Typical of quoting mistakes in shell scripts, .env files, or docker-compose/YAML values parsed as floats.

Common situations: docker-compose YAML written as UNSLOTH_CPU_THREADS: 8.0 (parsed as float string), stray whitespace/units in .env files, CI variables injected with a suffix, k8s ConfigMap values copied from documentation with units.

Related errors

• The executable at {binary} is not stable-diffusion.cpp: its
• Error: Invalid UNSLOTH_CPU_THREADS value {configured!r}: {ex
• Could not find a free port in range {start}-{start + max_att
• Native path grants require the managed desktop backend.
• Native path grant secret is invalid.

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