{"record":{"id":"5a08a48dd1b55db1","repo":"unslothai/unsloth","slug":"unsloth-cpu-threads-must-be-a-positive-integer","errorCode":null,"errorMessage":"UNSLOTH_CPU_THREADS must be a positive integer","messagePattern":"UNSLOTH_CPU_THREADS must be a positive integer","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"studio/backend/utils/cpu_threads.py","lineNumber":33,"sourceCode":")\n\n\ndef configure_cpu_threads(env: Optional[MutableMapping[str, str]] = None) -> None:\n    \"\"\"Apply ``UNSLOTH_CPU_THREADS`` to native CPU pools when configured.\n\n    Must run before importing libraries that initialize an OpenMP or BLAS\n    pool. Library-specific vars are left untouched so users can override a\n    single runtime independently.\n    \"\"\"\n    environ = os.environ if env is None else env\n    configured = environ.get(\"UNSLOTH_CPU_THREADS\", \"\").strip()\n    if not configured:\n        return\n\n    try:\n        thread_count = int(configured)\n    except ValueError as exc:\n        raise ValueError(\"UNSLOTH_CPU_THREADS must be a positive integer\") from exc\n    if thread_count < 1:\n        raise ValueError(\"UNSLOTH_CPU_THREADS must be a positive integer\")\n\n    value = str(thread_count)\n    for variable in _THREAD_POOL_ENV_VARS:\n        environ.setdefault(variable, value)\n","sourceCodeStart":15,"sourceCodeEnd":40,"githubUrl":"https://github.com/unslothai/unsloth/blob/203007d19051dcd2ae33876786d117c99f6b0368/studio/backend/utils/cpu_threads.py#L15-L40","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Set the variable to a bare positive integer: UNSLOTH_CPU_THREADS=8","Check for quoting/parsing issues in .env, docker-compose, or Helm values (e.g. 8.0 vs 8)","Unset the variable entirely if you want library defaults — the helper returns silently when it is empty"],"exampleFix":"# before (docker-compose)\nenvironment:\n  - UNSLOTH_CPU_THREADS=8.0   # int('8.0') raises\n\n# after\nenvironment:\n  - UNSLOTH_CPU_THREADS=8","handlingStrategy":"validation","validationCode":"import os\n\ndef validate_cpu_threads_env(env=None) -> int | None:\n    env = env or os.environ\n    raw = env.get(\"UNSLOTH_CPU_THREADS\", \"\").strip()\n    if not raw:\n        return None\n    try:\n        n = int(raw)\n    except ValueError:\n        raise ValueError(f\"UNSLOTH_CPU_THREADS={raw!r} is not an integer\")\n    if n < 1:\n        raise ValueError(f\"UNSLOTH_CPU_THREADS={raw!r} must be >= 1\")\n    return n","typeGuard":null,"tryCatchPattern":null,"preventionTips":["In .env files and compose YAML write bare integers (UNSLOTH_CPU_THREADS=8, never 8.0 or '8 cores')","Fail fast at container startup with a validation probe before the heavy imports run","Remember the check happens once, before library imports — a bad value kills the process at boot"],"tags":["environment","configuration","cpu","startup"],"backgroundTag":null,"analyzedSha":"203007d19051dcd2ae33876786d117c99f6b0368","analyzedAt":"2026-08-15T02:48:39.846Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}