{"record":{"id":"a8cfe367fdd861eb","repo":"docling-project/docling","slug":"format-format-is-not-supported-in-convert-strin","errorCode":null,"errorMessage":"format {format} is not supported in `convert_string`","messagePattern":"format (.+?) is not supported in `convert_string`","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"docling/document_converter.py","lineNumber":667,"sourceCode":"            return self.convert(doc_stream)\n        elif format == InputFormat.HTML:\n            if not name.endswith(\".html\"):\n                name += \".html\"\n\n            buff = BytesIO(content.encode(\"utf-8\"))\n            doc_stream = DocumentStream(name=name, stream=buff)\n\n            return self.convert(doc_stream)\n        elif format == InputFormat.XML_DOCLANG:\n            if not name.endswith((\".dclg\", \".dclg.xml\")):\n                name += \".dclg.xml\"\n\n            buff = BytesIO(content.encode(\"utf-8\"))\n            doc_stream = DocumentStream(name=name, stream=buff)\n\n            return self.convert(doc_stream)\n        else:\n            raise ValueError(f\"format {format} is not supported in `convert_string`\")\n\n    def _convert(\n        self, conv_input: _DocumentConversionInput, raises_on_error: bool\n    ) -> Iterator[ConversionResult]:\n        start_time = time.monotonic()\n\n        for input_batch in chunkify(\n            conv_input.docs(self.format_to_options),\n            settings.perf.doc_batch_size,  # pass format_options\n        ):\n            _log.info(\"Going to convert document batch...\")\n            process_func = partial(\n                self._process_document, raises_on_error=raises_on_error\n            )\n\n            if (\n                settings.perf.doc_batch_concurrency > 1\n                and settings.perf.doc_batch_size > 1","sourceCodeStart":649,"sourceCodeEnd":685,"githubUrl":"https://github.com/docling-project/docling/blob/61d76f1ff3f8428065465889f7b4577da7df704c/docling/document_converter.py#L649-L685","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","solutions":["For binary formats (PDF, Office, images), wrap the bytes in a DocumentStream and call convert() instead: DocumentStream(name='file.pdf', stream=BytesIO(data)).","For HTML/Markdown/Docling-XML content, pass the matching InputFormat (HTML, MD, XML_DOCLANG) so convert_string takes one of its supported branches.","Write the content to a temporary file and call convert(path) if constructing a DocumentStream is awkward."],"exampleFix":"# before\nres = converter.convert_string(pdf_bytes.decode('latin-1'), format=InputFormat.PDF)  # ValueError\n\n# after\nfrom io import BytesIO\nfrom docling.datamodel.base_models import DocumentStream\nstream = DocumentStream(name='doc.pdf', stream=BytesIO(pdf_bytes))\nres = next(converter.convert(stream))","handlingStrategy":"validation","validationCode":"from docling.datamodel.base_models import InputFormat\nSTRING_FORMATS = {InputFormat.HTML, InputFormat.MD, InputFormat.XML_DOCLANG}\nif fmt not in STRING_FORMATS:\n    raise SystemExit(f'{fmt} requires convert() with a DocumentStream, not convert_string()')","typeGuard":"def is_convert_string_format(fmt: InputFormat) -> bool:\n    return fmt in {InputFormat.HTML, InputFormat.MD, InputFormat.XML_DOCLANG}","tryCatchPattern":"try:\n    res = converter.convert_string(content, format=fmt)\nexcept ValueError as e:\n    if 'not supported in `convert_string`' in str(e):\n        res = next(converter.convert(DocumentStream(name='doc', stream=BytesIO(content.encode()))))\n    else:\n        raise","preventionTips":["Route binary formats (PDF/Office/images) through convert() with DocumentStream, not convert_string().","Keep a small allowlist of string-safe formats at the call site and branch on it."],"tags":["api-misuse","input-format","convert-string"],"backgroundTag":null,"analyzedSha":"61d76f1ff3f8428065465889f7b4577da7df704c","analyzedAt":"2026-08-14T23:53:18.727Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}