{"record":{"id":"681d6803b27aa161","repo":"unslothai/unsloth","slug":"error-invalid-unsloth-cpu-threads-value-raw-r","errorCode":null,"errorMessage":"Error: Invalid UNSLOTH_CPU_THREADS value {_raw!r}: {exc}","messagePattern":"Error: Invalid UNSLOTH_CPU_THREADS value (.+?): (.+?)","errorType":"console","errorClass":"SystemExit","httpStatus":null,"severity":"error","filePath":"studio/backend/main.py","lineNumber":194,"sourceCode":"# Backend dir on sys.path so _platform_compat imports under `uvicorn main:app`.\n_backend_dir = str(_Path(__file__).parent)\nif _backend_dir not in sys.path:\n    sys.path.insert(0, _backend_dir)\n\n# OS trust store for TLS before anything opens a connection: behind a\n# TLS-inspecting proxy certifi alone rejects every Hub request.\nfrom utils.native_tls import activate_native_tls\n\nactivate_native_tls()\n\n# `uvicorn main:app` bypasses run.py; seed thread caps here too.\nfrom utils.cpu_threads import configure_cpu_threads\n\ntry:\n    configure_cpu_threads()\nexcept ValueError as exc:\n    _raw = os.environ.get(\"UNSLOTH_CPU_THREADS\")\n    raise SystemExit(f\"Error: Invalid UNSLOTH_CPU_THREADS value {_raw!r}: {exc}\") from None\n\n# Anaconda/conda-forge Python: seed platform._sys_version_cache before attrs -> rich ->\n# structlog -> platform crashes. See https://github.com/python/cpython/issues/102396\nimport _platform_compat  # noqa: F401\n\n# Direct `uvicorn main:app` bypasses run.py, so re-export here too. Required BEFORE the\n# unsloth-zoo import below, whose LLAMA_CPP_DEFAULT_DIR binding is import-time.\nfrom utils.paths.storage_roots import studio_root as _studio_root\n\n# Same reason, same deadline: unsloth_zoo.compiler reads UNSLOTH_COMPILE_LOCATION\n# at import time, and without this a direct start falls back to a CWD-relative\n# unsloth_compiled_cache (on Windows that is the user profile).\nfrom utils.paths.storage_roots import setup_cache_env as _setup_cache_env\n\ntry:\n    _setup_cache_env()\nexcept Exception:  # noqa: BLE001\n    pass","sourceCodeStart":176,"sourceCodeEnd":212,"githubUrl":"https://github.com/unslothai/unsloth/blob/203007d19051dcd2ae33876786d117c99f6b0368/studio/backend/main.py#L176-L212","documentation":"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.","triggerScenarios":"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.","commonSituations":"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).","solutions":["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.","If set in docker-compose/Kubernetes, check the deployment manifests for an empty or interpolated value and correct it.","After fixing, restart the backend; the process exits before serving so no stale state exists."],"exampleFix":"# before\nexport UNSLOTH_CPU_THREADS=  # empty -> SystemExit\n# after\nunset UNSLOTH_CPU_THREADS        # auto-detect\n# or\nexport UNSLOTH_CPU_THREADS=8","handlingStrategy":"validation","validationCode":"import os\n\ndef cpu_threads_env_valid() -> bool:\n    raw = os.environ.get(\"UNSLOTH_CPU_THREADS\")\n    if raw is None:\n        return True  # auto-detect\n    try:\n        n = int(raw)\n    except ValueError:\n        return False\n    return n >= 1","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Set UNSLOTH_CPU_THREADS only to positive integers; unset it to use auto-detection.","In deployment manifests, lint env files for empty values ('KEY=').","Add a preflight check in deploy scripts that validates the env before exec'ing the server."],"tags":["env","config","startup","cpu-threads"],"backgroundTag":null,"analyzedSha":"203007d19051dcd2ae33876786d117c99f6b0368","analyzedAt":"2026-08-15T02:48:39.846Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}