What causes "PGPT_WORKER_MODE is required" in zylon-ai/private-gpt?

Export an explicit mode: export PGPT_WORKER_MODE=celery (or arq) before starting the worker

zylon-ai/private-gpt · error · ValueError

PGPT_WORKER_MODE is required

Error message

PGPT_WORKER_MODE is required

What it means

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.

Source

Thrown at private_gpt/worker/registry.py:30

        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

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; }

Example fix

# docker-compose.yml - before
environment:
  PGPT_WORKER_MODE: ${WORKER_MODE}

# after
environment:
  PGPT_WORKER_MODE: ${WORKER_MODE:-celery}

Defensive patterns

Strategy: validation

Validate before calling

import os

mode = os.environ.get("PGPT_WORKER_MODE", "").strip()
if not mode:
    raise SystemExit("PGPT_WORKER_MODE is required (e.g. 'celery' or 'arq')")

Type guard

null

Try / catch

try:
    run_worker(args)
except ValueError as e:
    if "is required" in str(e):
        raise SystemExit("set PGPT_WORKER_MODE before starting the worker")
    raise

Prevention

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

When it happens

Trigger: 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.

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

Related errors

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