docling-project/docling · error · ConversionError

No pipeline could be initialized for format {format}

Error message

No pipeline could be initialized for format {format}

What it means

_initialize_pipeline calls _get_pipeline(format) and raises ConversionError when it returns None — i.e. no registered pipeline accepts the given input format. Pipelines come from the format_options map (defaults or user-provided); a format with no matching FormatOption, or one whose pipeline class rejects the format, yields None. The docstring also notes related failures for bad artifacts_path and missing local model files.

Source

Thrown at docling/document_converter.py:438

        ).hexdigest()

    def initialize_pipeline(self, format: InputFormat):
        """Initialize the conversion pipeline for the selected format.

        Args:
            format: The input format for which to initialize the pipeline.

        Raises:
            ConversionError: If no pipeline could be initialized for the
                given format.
            RuntimeError: If `artifacts_path` is set in
                `docling.datamodel.settings.settings` when required by
                the pipeline, but points to a non-directory file.
            FileNotFoundError: If local model files are not found.
        """
        pipeline = self._get_pipeline(doc_format=format)
        if pipeline is None:
            raise ConversionError(
                f"No pipeline could be initialized for format {format}"
            )

    @validate_call(config=ConfigDict(strict=True))
    def convert(
        self,
        source: Union[Path, str, DocumentStream, HttpSource],  # TODO review naming
        headers: Optional[dict[str, str]] = None,
        raises_on_error: bool = True,
        max_num_pages: int = sys.maxsize,
        max_file_size: int = sys.maxsize,
        page_range: PageRange = DEFAULT_PAGE_RANGE,
    ) -> ConversionResult:
        """Convert one document fetched from a file path, URL, or DocumentStream.

        Note: If the document content is given as a string (Markdown or HTML
        content), use the `convert_string` method.

View on GitHub (pinned to 61d76f1ff3)

Solutions

  1. Add a FormatOption for the format (or use full defaults) when constructing DocumentConverter.
  2. Check InputFormat detection before converting and route unsupported types elsewhere.
  3. Catch ConversionError and surface a clear 'unsupported format' message to your users.

Example fix

# before
converter = DocumentConverter(format_options={InputFormat.PDF: PdfFormatOption()})
converter.initialize_pipeline(InputFormat.HTML)  # raises

# after
converter = DocumentConverter(  # defaults cover HTML
    format_options={InputFormat.PDF: PdfFormatOption()},
)
Defensive patterns

Strategy: validation

Validate before calling

supported = set(converter.format_to_options.keys()) if hasattr(converter, "format_to_options") else None
if supported is not None and fmt not in supported:
    raise ValueError(f"No pipeline for {fmt}; known: {sorted(supported)}")

Try / catch

try:
    converter.initialize_pipeline(fmt)
except ConversionError as e:
    if "No pipeline" in str(e):
        raise ValueError(f"Unsupported input format: {fmt}") from e
    raise

Prevention

When it happens

Trigger: DocumentConverter.initialize_pipeline(InputFormat.X) where no FormatOption/pipeline covers X; restricting format_options so the requested format has no entry; passing a format the selected pipeline's accepts_format does not include.

Common situations: Custom converters built with only some format_options and then fed a document of another type; slim installs lacking default pipelines; formats filtered out via allowed_formats but converted anyway.

Related errors

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