{"record":{"id":"56d3695a466f343d","repo":"zylon-ai/private-gpt","slug":"unsupported-pgpt-worker-mode-name-r-registered","errorCode":null,"errorMessage":"Unsupported PGPT_WORKER_MODE={name!r}. Registered modes: {supported_modes}","messagePattern":"Unsupported PGPT_WORKER_MODE=(.+?)\\. Registered modes: (.+?)","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"private_gpt/worker/registry.py","lineNumber":22,"sourceCode":"WorkerModeHandler = Callable[[Sequence[str]], None]\n\n_worker_modes: dict[str, WorkerModeHandler] = {}\n\n\ndef register_worker_mode(name: str, handler: WorkerModeHandler) -> None:\n    normalized_name = name.strip().lower()\n    if not normalized_name:\n        raise ValueError(\"Worker mode name cannot be empty\")\n    _worker_modes[normalized_name] = handler\n\n\ndef get_worker_mode(name: str) -> WorkerModeHandler:\n    normalized_name = name.strip().lower()\n    try:\n        return _worker_modes[normalized_name]\n    except KeyError as exc:\n        supported_modes = \", \".join(sorted(_worker_modes))\n        raise ValueError(\n            f\"Unsupported PGPT_WORKER_MODE={name!r}. Registered modes: {supported_modes}\"\n        ) from exc\n\n\ndef run_worker(args: Sequence[str] = ()) -> None:\n    mode = os.environ.get(\"PGPT_WORKER_MODE\", \"\").strip()\n    if not mode:\n        raise ValueError(\"PGPT_WORKER_MODE is required\")\n    get_worker_mode(mode)(args)\n","sourceCodeStart":4,"sourceCodeEnd":32,"githubUrl":"https://github.com/zylon-ai/private-gpt/blob/4a030776a31a901ad80b1bf4d7faa2c1a367efbb/private_gpt/worker/registry.py#L4-L32","documentation":"Raised by get_worker_mode when PGPT_WORKER_MODE (after strip+lowercase normalization) has no registered handler in the _worker_modes registry. run_worker looks up the mode by name; valid names are those registered at import time (e.g. 'celery', 'arq'). The message lists exactly which modes are registered, so a typo or an unavailable/failed-to-import mode is immediately visible.","triggerScenarios":"PGPT_WORKER_MODE=Celery with a trailing space or invisible character that still fails normalization after strip/lower; PGPT_WORKER_MODE=rq or taskiq (modes that were never implemented); a custom mode whose registration module was not imported before run_worker; a k8s ConfigMap value with quotes included ('\"celery\"').","commonSituations":"Copy-paste from docs of a mode name that does not exist in the installed version; upgrading private-gpt where a mode was renamed or removed; custom deployments registering their own handler but forgetting the import that performs register_worker_mode.","solutions":["Set PGPT_WORKER_MODE to one of the names listed in the error message (exact, lowercase)","Strip surrounding quotes/whitespace in the environment value (check with: printf '%s' \"$PGPT_WORKER_MODE\" | od -c)","If using a custom mode, ensure its module calls register_worker_mode(...) before run_worker executes (import it in the worker entrypoint)","Pin/verify the private-gpt version whose registry actually contains the mode you configured"],"exampleFix":"# before\nPGPT_WORKER_MODE=\"celery\"   # quotes end up inside the value\n\n# after\nPGPT_WORKER_MODE=celery","handlingStrategy":"validation","validationCode":"import os\nfrom private_gpt.worker.registry import get_worker_mode\n\nmode = os.environ.get(\"PGPT_WORKER_MODE\", \"\").strip().lower()\ntry:\n    get_worker_mode(mode)  # dry-run lookup before doing real work\nexcept ValueError:\n    raise SystemExit(f\"bad PGPT_WORKER_MODE={mode!r}\")","typeGuard":"null","tryCatchPattern":"try:\n    run_worker(args)\nexcept ValueError as e:\n    if \"Unsupported PGPT_WORKER_MODE\" in str(e):\n        # message lists valid modes; print and fail fast\n        raise SystemExit(str(e))\n    raise","preventionTips":["Set PGPT_WORKER_MODE as a bare lowercase literal (celery/arq) without quotes or spaces","Validate the value in deployment tooling with printf '%s' \"$PGPT_WORKER_MODE\" | od -c to catch hidden characters","For custom modes, guarantee the registering module is imported in the worker entrypoint","Pin the private-gpt version so the set of registered modes cannot drift silently"],"tags":["worker","configuration","environment-variables","registry"],"backgroundTag":null,"analyzedSha":"4a030776a31a901ad80b1bf4d7faa2c1a367efbb","analyzedAt":"2026-08-15T03:51:26.951Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}