zylon-ai/private-gpt · critical · ValueError

Unsupported scheduler.chat.mode={self.scheduler.chat.mode!r}

Error message

Unsupported scheduler.chat.mode={self.scheduler.chat.mode!r}. Supported chat scheduler modes are 'local' and 'arq'.

What it means

Startup-time ValueError from the root Settings model_validator: scheduler.chat.mode must be 'local' or 'arq'. The chat scheduler selects whether chat requests run in-process ('local') or are dispatched to an ARQ Redis worker ('arq'); any other value aborts settings loading and the app fails to boot.

Source

Thrown at private_gpt/settings/settings.py:1866

    sandbox: SandboxSettings
    bash: BashSettings
    code_execution: CodeExecutionSettings
    web_fetch: WebFetchSettings
    web_search: WebSearchSettings
    database_query: DatabaseQuerySettings
    brave: BraveSearchSettings
    skills: SkillSettings
    transformation: TransformationSettings
    semaphore: SemaphoreSettings
    scheduler: SchedulerConfig = Field(
        default_factory=SchedulerConfig,
        description="Scheduler configuration for chat and tool workers.",
    )

    @model_validator(mode="after")
    def validate_chat_scheduler_configuration(self) -> "Settings":
        if self.scheduler.chat.mode not in {"local", "arq"}:
            raise ValueError(
                f"Unsupported scheduler.chat.mode={self.scheduler.chat.mode!r}. "
                "Supported chat scheduler modes are 'local' and 'arq'."
            )

        if self.scheduler.tools.mode not in {"local", "celery"}:
            raise ValueError(
                f"Unsupported scheduler.tools.mode={self.scheduler.tools.mode!r}. "
                "Supported tool scheduler modes are 'local' and 'celery'."
            )

        if self.scheduler.tools.mode == "celery" and self.scheduler.chat.mode != "arq":
            raise ValueError(
                f"scheduler.tools.mode={self.scheduler.tools.mode!r} requires "
                "scheduler.chat.mode='arq' so tool callbacks can resume shared "
                "chat state."
            )

        if self.scheduler.chat.mode == "local":

View on GitHub (pinned to 4a030776a3)

Solutions

Set scheduler.chat.mode to 'local' for in-process execution or 'arq' for the Redis-backed chat worker.
Search all config layers (settings.yaml, settings-<profile>.yaml, env vars) for the key and remove stale duplicates.
If you meant Celery for tools, put it under scheduler.tools.mode and pair it with chat mode 'arq'.
Re-run startup and check the earliest log line — settings validation fails before serving.

Example fix

# before
scheduler:
  chat:
    mode: celery
# after
scheduler:
  chat:
    mode: arq

Defensive patterns

Strategy: validation

Validate before calling

mode = cfg.get('scheduler', {}).get('chat', {}).get('mode')
assert mode in {'local', 'arq'}, f'bad scheduler.chat.mode: {mode!r}'

Type guard

const isChatMode = (m: unknown): m is 'local' | 'arq' => m === 'local' || m === 'arq';

Prevention

Use a JSON schema / enum lint for scheduler modes in config reviews.
Remember: chat modes are local|arq; tools modes are local|celery — never copy one into the other.
Boot the app (or just import Settings) in CI to catch config errors pre-deploy.

When it happens

Trigger: settings.yaml with scheduler.chat.mode: celery (the classic mistake — celery is valid only for tools), 'redis', 'k8s', or a typo like 'lokal'; env var override with a stale value from an older config schema; empty string after a templating step removed the value.

Common situations: Copy-pasting scheduler config from docs for the tools worker into the chat section; upgrading versions where the mode key was renamed and old values linger; per-environment overlays not updated after the arq migration.

Related errors

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