docling-project/docling · error · DocumentLoadError

Could not initialize the WebVTT backend for file with hash {

Error message

Could not initialize the WebVTT backend for file with hash {self.document_hash}.

What it means

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.

Source

Thrown at docling/backend/webvtt_backend.py:75

    it to a DoclingDocument, following the W3C specs on https://www.w3.org/TR/webvtt1

    Each cue becomes a TextItem and the items are appended to the
    document body by the cue's start time.
    """

    @override
    def __init__(self, in_doc: InputDocument, path_or_stream: BytesIO | Path):
        super().__init__(in_doc, path_or_stream)

        self.content: str = ""
        try:
            if isinstance(self.path_or_stream, BytesIO):
                self.content = self.path_or_stream.getvalue().decode("utf-8")
            if isinstance(self.path_or_stream, Path):
                with open(self.path_or_stream, encoding="utf-8") as f:
                    self.content = f.read()
        except Exception as e:
            raise DocumentLoadError(
                "Could not initialize the WebVTT backend for file with hash "
                f"{self.document_hash}."
            ) from e

    @override
    def is_valid(self) -> bool:
        return WebVTTFile.verify_signature(self.content)

    @classmethod
    @override
    def supports_pagination(cls) -> bool:
        return False

    @override
    def unload(self):
        if isinstance(self.path_or_stream, BytesIO):
            self.path_or_stream.close()
        self.path_or_stream = None

View on GitHub (pinned to 61d76f1ff3)

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.

Example fix

# before
result = converter.convert(Path("captions.vtt"))  # UTF-16 file -> DocumentLoadError

# after
raw = Path("captions.vtt").read_bytes().decode("utf-16").encode("utf-8")
result = converter.convert(BytesIO(raw))

Defensive patterns

Strategy: try-catch

Validate before calling

from pathlib import Path

def vtt_readable_as_utf8(path: Path) -> bool:
    try:
        path.read_text(encoding="utf-8")
        return True
    except (UnicodeDecodeError, OSError):
        return False

Try / catch

from docling.datamodel.base_docs import DocumentLoadError

try:
    result = converter.convert(vtt_path)
except DocumentLoadError as e:
    logger.error("bad VTT input %s: %s (cause: %s)", vtt_path, e, e.__cause__)

Prevention

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.

When it happens

Trigger: 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.

Common situations: 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.

Related errors

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