unslothai/unsloth · critical · SystemExit

Error: Invalid UNSLOTH_CPU_THREADS value {configured!r}: {ex

Error message

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

What it means

Fatal startup error (SystemExit) from studio/backend/run.py: configure_cpu_threads() parsed the UNSLOTH_CPU_THREADS environment variable and raised ValueError because the value is not a positive integer. It runs before any heavy import so thread-pool sizing is correct; a bad value kills the process immediately with the offending value echoed.

Source

Thrown at studio/backend/run.py:135

    os.execv(sys.executable, argv)


# Suppress C-level dependency warnings globally (e.g. SwigPyPacked).
os.environ["PYTHONWARNINGS"] = "ignore"

# Add the backend dir to sys.path early so local modules import.
backend_dir = Path(__file__).parent
if str(backend_dir) not in sys.path:
    sys.path.insert(0, str(backend_dir))

# First, so these vars land before anything below can size an OpenMP/BLAS pool. Imports stdlib only.
from utils.cpu_threads import configure_cpu_threads

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

# Windows ROCm ships no distributed backend, so torchao and the CUDA-only xformers both die on import,
# taking diffusers/transformers with them. A stub only seeds a name nothing has imported yet, so both
# must precede the first import below. No-op on other runtimes.
from core._torchao_stub import (
    install_torchao_windows_rocm_stub,
    install_xformers_windows_rocm_stub,
)

install_xformers_windows_rocm_stub()
install_torchao_windows_rocm_stub()

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

from loggers import get_logger, install_uvicorn_duplicate_exception_filter

View on GitHub (pinned to 203007d190)

Solutions

1. Unset or fix the variable to a plain positive integer: export UNSLOTH_CPU_THREADS=8.
2. Remove the line from .env/compose if thread pinning is not needed — absence is fine.
3. Sanitize in launch scripts: ${UNSLOTH_CPU_THREADS:-} guards or validate before export.

Example fix

# before
UNSLOTH_CPU_THREADS="8 threads"

# after
UNSLOTH_CPU_THREADS=8

#!/usr/bin/env bash
# Validate before launching
if [ -n "${UNSLOTH_CPU_THREADS:-}" ]; then
  [[ "$UNSLOTH_CPU_THREADS" =~ ^[1-9][0-9]*$ ]] || { echo "UNSLOTH_CPU_THREADS must be a positive integer, got '$UNSLOTH_CPU_THREADS'"; exit 1; }
fi
exec unsloth studio "$@"

def valid_cpu_threads(v: str | None) -> bool:
    return v is None or (v.isdigit() and int(v) > 0)

When it happens

Trigger: UNSLOTH_CPU_THREADS='4,', '0', '-2', 'four', '2.5', or an empty string exported before `unsloth studio` starts; a .env file with a stray quote; CI passing the var with whitespace or a unit ('8threads').

Common situations: Copy-pasted .env lines; docker-compose env with quoting errors; shell loops exporting computed values that occasionally produce empty strings.

Related errors

• Error: Invalid UNSLOTH_CPU_THREADS value {_raw!r}: {exc}
• Could not find a free port in range {start}-{start + max_att
• UNSLOTH_CPU_THREADS must be a positive integer
• Add a Provider connection block before running this recipe.
• Unsupported attention_backend '{value}'. Use one of: {', '.j

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