docling-project/docling · error · ValueError

format {format} is not supported in `convert_string`

Error message

format {format} is not supported in `convert_string`

What it means

Raised by DocumentConverter.convert_string() when the InputFormat passed as `format` is not one of the string-convertible formats handled by that method. convert_string only supports formats whose content can be safely wrapped into an in-memory DocumentStream (HTML, Markdown, Docling XML-doctags, etc.); binary formats like PDF must go through convert() with a real file/BytesIO stream.

Source

Thrown at docling/document_converter.py:667

            return self.convert(doc_stream)
        elif format == InputFormat.HTML:
            if not name.endswith(".html"):
                name += ".html"

            buff = BytesIO(content.encode("utf-8"))
            doc_stream = DocumentStream(name=name, stream=buff)

            return self.convert(doc_stream)
        elif format == InputFormat.XML_DOCLANG:
            if not name.endswith((".dclg", ".dclg.xml")):
                name += ".dclg.xml"

            buff = BytesIO(content.encode("utf-8"))
            doc_stream = DocumentStream(name=name, stream=buff)

            return self.convert(doc_stream)
        else:
            raise ValueError(f"format {format} is not supported in `convert_string`")

    def _convert(
        self, conv_input: _DocumentConversionInput, raises_on_error: bool
    ) -> Iterator[ConversionResult]:
        start_time = time.monotonic()

        for input_batch in chunkify(
            conv_input.docs(self.format_to_options),
            settings.perf.doc_batch_size,  # pass format_options
        ):
            _log.info("Going to convert document batch...")
            process_func = partial(
                self._process_document, raises_on_error=raises_on_error
            )

            if (
                settings.perf.doc_batch_concurrency > 1
                and settings.perf.doc_batch_size > 1

View on GitHub (pinned to 61d76f1ff3)

Solutions

1. For binary formats (PDF, Office, images), wrap the bytes in a DocumentStream and call convert() instead: DocumentStream(name='file.pdf', stream=BytesIO(data)).
2. For HTML/Markdown/Docling-XML content, pass the matching InputFormat (HTML, MD, XML_DOCLANG) so convert_string takes one of its supported branches.
3. Write the content to a temporary file and call convert(path) if constructing a DocumentStream is awkward.

Example fix

# before
res = converter.convert_string(pdf_bytes.decode('latin-1'), format=InputFormat.PDF)  # ValueError

# after
from io import BytesIO
from docling.datamodel.base_models import DocumentStream
stream = DocumentStream(name='doc.pdf', stream=BytesIO(pdf_bytes))
res = next(converter.convert(stream))

from docling.datamodel.base_models import InputFormat
STRING_FORMATS = {InputFormat.HTML, InputFormat.MD, InputFormat.XML_DOCLANG}
if fmt not in STRING_FORMATS:
    raise SystemExit(f'{fmt} requires convert() with a DocumentStream, not convert_string()')

def is_convert_string_format(fmt: InputFormat) -> bool:
    return fmt in {InputFormat.HTML, InputFormat.MD, InputFormat.XML_DOCLANG}

try:
    res = converter.convert_string(content, format=fmt)
except ValueError as e:
    if 'not supported in `convert_string`' in str(e):
        res = next(converter.convert(DocumentStream(name='doc', stream=BytesIO(content.encode()))))
    else:
        raise

When it happens

Trigger: Calling converter.convert_string(content, format=InputFormat.PDF) or any format not covered by the if/elif chain in convert_string (e.g. InputFormat.AUDIO, InputFormat.DOCX, InputFormat.PPTX).

Common situations: Developer tries to convert a base64-decoded PDF body or an Office file's bytes via convert_string because it is convenient for in-memory content; or passes a custom/unsupported InputFormat value after upgrading Docling and the enum gained new members.

Related errors

• ThreadedDoclingParseDocumentBackend only supports iter_pages
• Unexpected: {type(self.path_or_stream)=}
• Unexpected: {type(self.path_or_stream)=}
• path_or_stream must be Path or BytesIO
• Invalid document with hash {self.document_hash}

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