What causes "No default options configured for {format}" in docling-project/docling?

Register an explicit FormatOption for the format when building DocumentConverter(format_options={InputFormat.X: FormatOption(...)}) instead of relying on defaults.

docling-project/docling · error · RuntimeError

No default options configured for {format}

Error message

No default options configured for {format}

What it means

_get_default_options looks up the requested InputFormat in a hardcoded map of default FormatOption entries (PDF, DOCX, PPTX, VIDEO, VTT, LATEX, EMAIL, EPUB, EBCDIC, etc.). If the format has no entry in format_to_default_options, a RuntimeError is raised. This typically means the format enum exists but no default pipeline/backend is configured for it in this docling build (some formats require explicit options or extra dependencies).

Source

Thrown at docling/document_converter.py:311

        InputFormat.IMAGE: ImageFormatOption(),
        InputFormat.PDF: PdfFormatOption(),
        InputFormat.JSON_DOCLING: FormatOption(
            pipeline_cls=SimplePipeline, backend=DoclingJSONBackend
        ),
        InputFormat.AUDIO: AudioFormatOption(),
        InputFormat.VIDEO: VideoFormatOption(),
        InputFormat.VTT: FormatOption(
            pipeline_cls=SimplePipeline, backend=WebVTTDocumentBackend
        ),
        InputFormat.LATEX: LatexFormatOption(),
        InputFormat.EMAIL: EmailFormatOption(),
        InputFormat.EPUB: EpubFormatOption(),
        InputFormat.EBCDIC: EbcdicFormatOption(),
    }
    if (options := format_to_default_options.get(format)) is not None:
        return options
    else:
        raise RuntimeError(f"No default options configured for {format}")


class DocumentConverter:
    """Convert documents of various input formats to Docling documents.

    `DocumentConverter` is the main entry point for converting documents in Docling.
    It handles various input formats (PDF, DOCX, PPTX, images, HTML, Markdown, etc.)
    and provides both single-document and batch conversion capabilities.

    The conversion methods return a `ConversionResult` instance for each document,
    which wraps a `DoclingDocument` object if the conversion was successful, along
    with metadata about the conversion process.

    Attributes:
        allowed_formats: Allowed input formats.
        format_to_options: Mapping of formats to their options.
        initialized_pipelines: Cache of initialized pipelines keyed by
            (pipeline class, options hash).

View on GitHub (pinned to 61d76f1ff3)

Solutions

Register an explicit FormatOption for the format when building DocumentConverter(format_options={InputFormat.X: FormatOption(...)}) instead of relying on defaults.
Install the missing extras/backends for that format (e.g. the full docling package rather than slim).
Update docling so the format's default entry exists.

Example fix

# before
converter = DocumentConverter(allowed_formats=[InputFormat.SOME_FORMAT])

# after
from docling.datamodel.base_models import FormatOption
converter = DocumentConverter(
    format_options={InputFormat.SOME_FORMAT: FormatOption(pipeline_cls=..., backend=...)},
)

Defensive patterns

Strategy: validation

Validate before calling

from docling.datamodel.settings import _get_default_options  # or replicate the check
def has_default(fmt) -> bool:
    try:
        _get_default_options(fmt)
        return True
    except RuntimeError:
        return False

if not has_default(fmt):
    format_options[fmt] = FormatOption(pipeline_cls=MyPipeline, backend=MyBackend)

Try / catch

try:
    opts = _get_default_options(fmt)
except RuntimeError as e:
    if "No default options" in str(e):
        raise ValueError(f"Format {fmt} requires explicit FormatOption") from e
    raise

Prevention

Always pass explicit format_options for non-default formats instead of relying on defaults.
Prefer the full docling package over slim when you need broad format coverage.

When it happens

Trigger: Calling code paths that resolve default options for an InputFormat that is not in the map — e.g. an InputFormat whose support depends on installed extras or an enum value added without a default entry. Passing allowed_formats containing such a format then triggering default-option resolution.

Common situations: docling-slim installs missing optional backends; using a newer InputFormat enum against older default-option wiring; constructing a DocumentConverter with formats that need explicit FormatOption.

Related errors

AI-assisted analysis of docling-project/docling@61d76f1ff3 (2026-08-14). Data as JSON: /api/errors/5493cefefc17e651. Report an issue: GitHub.