zylon-ai/private-gpt · error · ValueError

Unknown scheduler.chat.mode: {mode}

Error message

Unknown scheduler.chat.mode: {mode}

What it means

Raised by ChatSchedulerFactory.__init__ when settings.scheduler.chat.mode is not a key in the _CHAT_SCHEDULERS mapping. The factory validates the mode eagerly at injection time so a bad scheduler config aborts startup rather than failing later on first use. The invalid mode value is included in the message.

Source

Thrown at private_gpt/components/streaming/tasks/chat_scheduler.py:65

    async def cancel(self, correlation_id: str) -> bool:
        return await abort_chat_job(correlation_id=correlation_id)


register_chat_scheduler("local", LocalChatScheduler)
register_chat_scheduler("arq", ArqChatScheduler)


@singleton
class ChatSchedulerFactory:
    @inject
    def __init__(self, settings: Settings, injector: Injector) -> None:
        self._settings = settings
        self._injector = injector
        self._scheduler: BaseChatScheduler | None = None

        mode = self._settings.scheduler.chat.mode
        if mode not in _CHAT_SCHEDULERS:
            raise ValueError(f"Unknown scheduler.chat.mode: {mode}")

    def get(self) -> BaseChatScheduler:
        if self._scheduler is None:
            mode = self._settings.scheduler.chat.mode
            provider = _CHAT_SCHEDULERS[mode]
            self._scheduler = (
                self._injector.get(provider)
                if isinstance(provider, type)
                else provider(self._injector)
            )
        return self._scheduler

View on GitHub (pinned to 4a030776a3)

Solutions

1. Set scheduler.chat.mode to a key present in _CHAT_SCHEDULERS (inspect private_gpt/components/streaming/tasks/chat_scheduler.py for the registered names)
2. Remove the setting entirely to fall back to the default mode if one applies
3. If adding a custom scheduler, register it in _CHAT_SCHEDULERS with the exact key you configure

Example fix

# before
scheduler:
  chat:
    mode: batch   # not registered
# after
scheduler:
  chat:
    mode: sequential   # a key present in _CHAT_SCHEDULERS

from private_gpt.components.streaming.tasks.chat_scheduler import _CHAT_SCHEDULERS

mode = settings.scheduler.chat.mode
if mode not in _CHAT_SCHEDULERS:
    raise ValueError(
        f"scheduler.chat.mode must be one of {sorted(_CHAT_SCHEDULERS)}, got {mode!r}"
    )

def is_known_chat_mode(mode: str) -> bool:
    from private_gpt.components.streaming.tasks.chat_scheduler import _CHAT_SCHEDULERS
    return mode in _CHAT_SCHEDULERS

When it happens

Trigger: Setting scheduler.chat.mode in settings.yaml to a string that is not one of the registered scheduler names; leftover config from an older version after the scheduler registry changed.

Common situations: Typos or casing differences (e.g. "Simple" vs the registered key); enabling an experimental scheduler whose extra/deps are documented elsewhere; config drift after upgrading.

Related errors

• Unsupported streaming provider: {settings.stream.broker}
• Unknown scheduler.tools.mode: {mode}
• Unsupported scheduler.chat.mode={self.scheduler.chat.mode!r}
• Unsupported scheduler.tools.mode={self.scheduler.tools.mode!
• scheduler.tools.mode={self.scheduler.tools.mode!r} requires

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