zylon-ai/private-gpt · error · ValueError

Unsupported PGPT_WORKER_MODE={name!r}. Registered modes: {su

Error message

Unsupported PGPT_WORKER_MODE={name!r}. Registered modes: {supported_modes}

What it means

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.

Source

Thrown at private_gpt/worker/registry.py:22

WorkerModeHandler = Callable[[Sequence[str]], None]

_worker_modes: dict[str, WorkerModeHandler] = {}


def register_worker_mode(name: str, handler: WorkerModeHandler) -> None:
    normalized_name = name.strip().lower()
    if not normalized_name:
        raise ValueError("Worker mode name cannot be empty")
    _worker_modes[normalized_name] = handler


def get_worker_mode(name: str) -> WorkerModeHandler:
    normalized_name = name.strip().lower()
    try:
        return _worker_modes[normalized_name]
    except KeyError as exc:
        supported_modes = ", ".join(sorted(_worker_modes))
        raise ValueError(
            f"Unsupported PGPT_WORKER_MODE={name!r}. Registered modes: {supported_modes}"
        ) from exc


def run_worker(args: Sequence[str] = ()) -> None:
    mode = os.environ.get("PGPT_WORKER_MODE", "").strip()
    if not mode:
        raise ValueError("PGPT_WORKER_MODE is required")
    get_worker_mode(mode)(args)

View on GitHub (pinned to 4a030776a3)

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

Example fix

# before
PGPT_WORKER_MODE="celery"   # quotes end up inside the value

# after
PGPT_WORKER_MODE=celery

Defensive patterns

Strategy: validation

Validate before calling

import os
from private_gpt.worker.registry import get_worker_mode

mode = os.environ.get("PGPT_WORKER_MODE", "").strip().lower()
try:
    get_worker_mode(mode)  # dry-run lookup before doing real work
except ValueError:
    raise SystemExit(f"bad PGPT_WORKER_MODE={mode!r}")

Type guard

null

Try / catch

try:
    run_worker(args)
except ValueError as e:
    if "Unsupported PGPT_WORKER_MODE" in str(e):
        # message lists valid modes; print and fail fast
        raise SystemExit(str(e))
    raise

Prevention

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

When it happens

Trigger: 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"').

Common situations: 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.

Related errors

AI-assisted analysis of zylon-ai/private-gpt@4a030776a3 (2026-08-15). Data as JSON: /api/errors/56d3695a466f343d. Report an issue: GitHub.