{"record":{"id":"0879f741eef480d6","repo":"docling-project/docling","slug":"invalid-webvtt-document","errorCode":null,"errorMessage":"Invalid WebVTT document.","messagePattern":"Invalid WebVTT document\\.","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"docling/backend/webvtt_backend.py","lineNumber":104,"sourceCode":"    def supports_pagination(cls) -> bool:\n        return False\n\n    @override\n    def unload(self):\n        if isinstance(self.path_or_stream, BytesIO):\n            self.path_or_stream.close()\n        self.path_or_stream = None\n\n    @classmethod\n    @override\n    def supported_formats(cls) -> set[InputFormat]:\n        return {InputFormat.VTT}\n\n    @override\n    def convert(self) -> DoclingDocument:\n        _log.debug(\"Starting WebVTT conversion...\")\n        if not self.is_valid():\n            raise RuntimeError(\"Invalid WebVTT document.\")\n\n        origin = DocumentOrigin(\n            filename=self.file.name or \"file\",\n            mimetype=\"text/vtt\",\n            binary_hash=self.document_hash,\n        )\n        doc = DoclingDocument(name=self.file.stem or \"file\", origin=origin)\n\n        vtt: WebVTTFile = WebVTTFile.parse(self.content)\n        cue_text: list[AnnotatedPar] = []\n        parents: list[AnnotatedText] = []\n\n        def _extract_components(\n            payload: list[WebVTTCueComponentWithTerminator],\n        ) -> None:\n            nonlocal cue_text, parents\n            if not cue_text:\n                cue_text.append(AnnotatedPar(items=[]))","sourceCodeStart":86,"sourceCodeEnd":122,"githubUrl":"https://github.com/docling-project/docling/blob/61d76f1ff3f8428065465889f7b4577da7df704c/docling/backend/webvtt_backend.py#L86-L122","documentation":"WebVTTBackend.convert() was called on a document that failed signature verification (content does not start with a valid WEBVTT header), so it raises RuntimeError instead of parsing garbage. In the normal DocumentConverter flow invalid backends are filtered out by format detection; this surfaces when convert() is invoked directly on an invalid backend.","triggerScenarios":"Constructing WebVTTBackend on a file whose content lacks the 'WEBVTT' magic (so is_valid() is False) and calling convert() anyway — e.g. manual backend usage, or a .vtt file that is actually SRT text.","commonSituations":"SRT files renamed to .vtt; empty or whitespace-prefixed caption files; custom code driving backends directly instead of DocumentConverter.","solutions":["Ensure the file starts with 'WEBVTT' on the first line; convert SRT to VTT (change header, commas to dots in timestamps).","Route conversion through DocumentConverter, which checks backend.is_valid() and reports an unsupported format instead of crashing.","If using the backend directly, guard with `if backend.is_valid(): backend.convert()`.","Strip a leading BOM or blank lines before the WEBVTT marker."],"exampleFix":"# before\nbackend = WebVTTBackend(in_doc, path_or_stream)\ndoc = backend.convert()  # RuntimeError if invalid\n\n# after\nbackend = WebVTTBackend(in_doc, path_or_stream)\nif not backend.is_valid():\n    raise ValueError(\"not a WebVTT document; convert SRT to VTT first\")\ndoc = backend.convert()","handlingStrategy":"validation","validationCode":"def is_probable_webvtt(content: str) -> bool:\n    return content.lstrip(\"\\ufeff\\ufeff \").startswith(\"WEBVTT\")","typeGuard":null,"tryCatchPattern":"try:\n    doc = backend.convert()\nexcept RuntimeError as e:\n    if \"Invalid WebVTT\" in str(e):\n        raise ValueError(\"input is not WebVTT; convert SRT to VTT first\") from e\n    raise","preventionTips":["Always call backend.is_valid() (or let DocumentConverter do format detection) before convert().","Convert SRT to VTT (header + timestamp comma->dot) upstream.","Strip BOM/blank lines preceding the WEBVTT marker."],"tags":["webvtt","subtitles","validation","format-detection"],"backgroundTag":null,"analyzedSha":"61d76f1ff3f8428065465889f7b4577da7df704c","analyzedAt":"2026-08-14T23:53:18.727Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}