{"record":{"id":"26b8414c20a3b207","repo":"docling-project/docling","slug":"could-not-initialize-the-webvtt-backend-for-file-w","errorCode":null,"errorMessage":"Could not initialize the WebVTT backend for file with hash {self.document_hash}.","messagePattern":"Could not initialize the WebVTT backend for file with hash (.+?)\\.","errorType":"exception","errorClass":"DocumentLoadError","httpStatus":null,"severity":"error","filePath":"docling/backend/webvtt_backend.py","lineNumber":75,"sourceCode":"    it to a DoclingDocument, following the W3C specs on https://www.w3.org/TR/webvtt1\n\n    Each cue becomes a TextItem and the items are appended to the\n    document body by the cue's start time.\n    \"\"\"\n\n    @override\n    def __init__(self, in_doc: InputDocument, path_or_stream: BytesIO | Path):\n        super().__init__(in_doc, path_or_stream)\n\n        self.content: str = \"\"\n        try:\n            if isinstance(self.path_or_stream, BytesIO):\n                self.content = self.path_or_stream.getvalue().decode(\"utf-8\")\n            if isinstance(self.path_or_stream, Path):\n                with open(self.path_or_stream, encoding=\"utf-8\") as f:\n                    self.content = f.read()\n        except Exception as e:\n            raise DocumentLoadError(\n                \"Could not initialize the WebVTT backend for file with hash \"\n                f\"{self.document_hash}.\"\n            ) from e\n\n    @override\n    def is_valid(self) -> bool:\n        return WebVTTFile.verify_signature(self.content)\n\n    @classmethod\n    @override\n    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","sourceCodeStart":57,"sourceCodeEnd":93,"githubUrl":"https://github.com/docling-project/docling/blob/61d76f1ff3f8428065465889f7b4577da7df704c/docling/backend/webvtt_backend.py#L57-L93","documentation":"The WebVTT backend constructor failed to read or UTF-8-decode the input (.vtt subtitle file) and wraps the underlying exception in DocumentLoadError. WebVTT is a UTF-8 text format; any decode failure or I/O error while loading the file/BytesIO aborts backend creation.","triggerScenarios":"Calling WebVTTBackend(in_doc, path_or_stream) with bytes that are not valid UTF-8 (e.g. UTF-16 exports, Latin-1 subtitle files, binary data), or a Path that cannot be opened/read.","commonSituations":"Windows-authored .vtt files saved as UTF-16 with BOM; mislabeled files with a .vtt extension that are actually SRT in another encoding; truncated downloads; unreadable file permissions.","solutions":["Re-encode the file to UTF-8 (e.g. iconv -f UTF-16 -t UTF-8 in.vtt > out.vtt).","Confirm the file really is WebVTT (starts with 'WEBVTT') and not SRT or binary; convert SRT to VTT first if needed.","Check the file is readable and not truncated (compare size, re-download).","Catch DocumentLoadError around conversion to skip corrupt inputs in batch jobs."],"exampleFix":"# before\nresult = converter.convert(Path(\"captions.vtt\"))  # UTF-16 file -> DocumentLoadError\n\n# after\nraw = Path(\"captions.vtt\").read_bytes().decode(\"utf-16\").encode(\"utf-8\")\nresult = converter.convert(BytesIO(raw))","handlingStrategy":"try-catch","validationCode":"from pathlib import Path\n\ndef vtt_readable_as_utf8(path: Path) -> bool:\n    try:\n        path.read_text(encoding=\"utf-8\")\n        return True\n    except (UnicodeDecodeError, OSError):\n        return False","typeGuard":null,"tryCatchPattern":"from docling.datamodel.base_docs import DocumentLoadError\n\ntry:\n    result = converter.convert(vtt_path)\nexcept DocumentLoadError as e:\n    logger.error(\"bad VTT input %s: %s (cause: %s)\", vtt_path, e, e.__cause__)","preventionTips":["Normalize all caption files to UTF-8 during ingestion.","Sniff and reject BOM-prefixed UTF-16 files before conversion.","In batch jobs, catch DocumentLoadError and quarantine the file."],"tags":["webvtt","subtitles","encoding","utf-8","document-load"],"backgroundTag":null,"analyzedSha":"61d76f1ff3f8428065465889f7b4577da7df704c","analyzedAt":"2026-08-14T23:53:18.727Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}