{"record":{"id":"cf722cddf956b30b","repo":"zylon-ai/private-gpt","slug":"pgpt-worker-mode-is-required","errorCode":null,"errorMessage":"PGPT_WORKER_MODE is required","messagePattern":"PGPT_WORKER_MODE is required","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"private_gpt/worker/registry.py","lineNumber":30,"sourceCode":"        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":12,"sourceCodeEnd":32,"githubUrl":"https://github.com/zylon-ai/private-gpt/blob/4a030776a31a901ad80b1bf4d7faa2c1a367efbb/private_gpt/worker/registry.py#L12-L32","documentation":"Raised by run_worker when the PGPT_WORKER_MODE environment variable is empty or contains only whitespace. Unlike the unsupported-mode error, this fires before any registry lookup: the worker entrypoint requires an explicit mode because there is no default backend for background task processing.","triggerScenarios":"Running the worker entrypoint in a shell/container where PGPT_WORKER_MODE was never exported; the variable set to an empty string by a template (env: PGPT_WORKER_MODE=${WORKER_MODE} with WORKER_MODE unset); docker-compose service that declares the variable but assigns nothing.","commonSituations":"First-time worker deployment missing the env var; CI/CD pipelines that define the variable only for some jobs; .env file with PGPT_WORKER_MODE= (empty right-hand side) that is silently loaded as empty.","solutions":["Export an explicit mode: export PGPT_WORKER_MODE=celery (or arq) before starting the worker","Fix empty templating: use a default in compose (${WORKER_MODE:-celery}) or remove the empty assignment in .env","Add a startup check in deployment scripts: [ -n \"$PGPT_WORKER_MODE\" ] || { echo 'PGPT_WORKER_MODE required'; exit 1; }"],"exampleFix":"# docker-compose.yml - before\nenvironment:\n  PGPT_WORKER_MODE: ${WORKER_MODE}\n\n# after\nenvironment:\n  PGPT_WORKER_MODE: ${WORKER_MODE:-celery}","handlingStrategy":"validation","validationCode":"import os\n\nmode = os.environ.get(\"PGPT_WORKER_MODE\", \"\").strip()\nif not mode:\n    raise SystemExit(\"PGPT_WORKER_MODE is required (e.g. 'celery' or 'arq')\")","typeGuard":"null","tryCatchPattern":"try:\n    run_worker(args)\nexcept ValueError as e:\n    if \"is required\" in str(e):\n        raise SystemExit(\"set PGPT_WORKER_MODE before starting the worker\")\n    raise","preventionTips":["Declare PGPT_WORKER_MODE with a concrete value in every worker service definition (compose, k8s, systemd)","Use ${VAR:-celery} style defaults in templated configs instead of ${VAR} which can resolve empty","Add preflight env checks in container entrypoints","Keep .env assignments non-empty: 'PGPT_WORKER_MODE=' silently creates the failure"],"tags":["worker","configuration","environment-variables","startup"],"backgroundTag":null,"analyzedSha":"4a030776a31a901ad80b1bf4d7faa2c1a367efbb","analyzedAt":"2026-08-15T03:51:26.951Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}