zylon-ai/private-gpt · error · ValueError

Unknown Docling mode: {docling_settings.mode}

Error message

Unknown Docling mode: {docling_settings.mode}

What it means

Raised by DoclingReaderFactory.create_reader when settings.docling.mode has no registered provider in the module-level _PROVIDERS dict. The factory pattern allows pluggable Docling modes via register_docling_mode(); the stock registry contains only 'api' (DoclingApiReader). This error means the configured mode string does not match any registered provider — either a typo or a mode whose registering module was never imported.

Source

Thrown at private_gpt/components/readers/factories/docling.py:39

_PROVIDERS: dict[str, DoclingModeProvider] = {
    "api": _create_docling_api_reader,
}


def register_docling_mode(mode: str, provider: DoclingModeProvider) -> None:
    _PROVIDERS[mode] = provider


class DoclingReaderFactory(ReaderFactory):
    def create_reader(self, extension: str | None = None) -> IngestionReader:
        del extension

        docling_settings = self.settings.docling
        provider = _PROVIDERS.get(docling_settings.mode)
        if provider is None:
            raise ValueError(f"Unknown Docling mode: {docling_settings.mode}")
        return provider(self)

View on GitHub (pinned to 4a030776a3)

Solutions

1. Set docling.mode: api in settings.yaml — it is the only mode private-gpt registers out of the box.
2. If you added a custom mode, ensure the module calling register_docling_mode('yourmode', provider) is imported before DoclingReaderFactory.create_reader runs (register at package import time).
3. Check for typos/whitespace in the mode value.

Example fix

# plugin registering a custom mode — make sure this import happens at startup
from private_gpt.components.readers.factories.docling import register_docling_mode

def _create_local_reader(factory):
    from myapp.readers import LocalDoclingReader
    return LocalDoclingReader()

register_docling_mode('local', _create_local_reader)

from private_gpt.components.readers.factories import docling as dl

def validate_docling_mode(mode: str) -> None:
    if mode not in dl._PROVIDERS:
        raise SystemExit(f"docling.mode '{mode}' unknown; registered modes: {sorted(dl._PROVIDERS)}")

validate_docling_mode(settings().docling.mode)

from private_gpt.components.readers.factories import docling as dl

def is_registered_docling_mode(mode: str) -> bool:
    return mode in dl._PROVIDERS

try:
    reader = factory.create_reader()
except ValueError as e:
    if "Unknown Docling mode" in str(e):
        raise ConfigurationError(f"set docling.mode to one of {sorted(dl._PROVIDERS)}") from e
    raise

When it happens

Trigger: settings.docling.mode set to anything other than 'api' (the only built-in), or a custom mode registered via register_docling_mode() in a plugin/module that has not been imported when the factory runs. Fires when the reader registry builds the docling reader during ingestion startup.

Common situations: Configs from other Docling-integrating tools that use mode names like 'local' or 'remote' which private-gpt does not ship; a fork/plugin that previously registered a custom mode and the import was removed during upgrade; typo in settings.yaml.

Related errors

• Embedding mode '{mode}' is not supported. Available: {availa
• API base URL and poll interval must be provided in async mod
• No OCR languages specified.
• OCR model {settings().docling.ocr_model} not supported
• Language {lang} not supported by EasyOCR

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