docling-project/docling · error · DocumentLoadError

Unknown EBCDIC codec {encoding!r}.

Error message

Unknown EBCDIC codec {encoding!r}.

What it means

The EBCDIC backend's field decoder resolves its text codec with codecs.getdecoder(encoding); if Python's codec registry does not know the name (LookupError), it raises this DocumentLoadError echoing the offending encoding string. The encoding comes from EbcdicBackendOptions.encoding (directly or via the layout file), and it must be a codec Python actually ships — EBCDIC pages exist under names like cp037, cp500, cp1026, not under friendly aliases such as 'EBCDIC-US'.

Source

Thrown at docling/backend/ebcdic_backend.py:68

# Sign nibbles of packed and zoned decimals: 0xb and 0xd are negative, every
# other value (0xa, 0xc, 0xe, 0xf and unsigned digits) is positive.
_NEGATIVE_SIGNS = frozenset({0xB, 0xD})

_DecodedValue = Union[str, int, Decimal]


class EbcdicDecodeError(DocumentLoadError):
    """A field could not be decoded with the configured layout."""


class _FieldDecoder:
    """Decode single EBCDIC fields into Python values."""

    def __init__(self, encoding: str, strip_control_characters: bool) -> None:
        try:
            self._decode_text = codecs.getdecoder(encoding)
        except LookupError as exc:
            raise DocumentLoadError(f"Unknown EBCDIC codec {encoding!r}.") from exc
        self._strip_control_characters = strip_control_characters
        self._decoders: dict[EbcdicFieldType, Callable[[bytes], _DecodedValue]] = {
            EbcdicFieldType.STRING: self._string,
            EbcdicFieldType.INTEGER: lambda data: self._binary(data, signed=True),
            EbcdicFieldType.UNSIGNED_INTEGER: lambda data: self._binary(
                data, signed=False
            ),
            EbcdicFieldType.PACKED_DECIMAL: self._packed_decimal,
            EbcdicFieldType.ZONED_DECIMAL: self._zoned_decimal,
        }

    def decode(self, data: bytes, field: EbcdicField) -> _DecodedValue:
        """Decode the bytes of one field as described by its layout."""
        try:
            value = self._decoders[field.type](data)
        except (ArithmeticError, LookupError, UnicodeError, ValueError) as exc:
            raise EbcdicDecodeError(
                f"Cannot decode field {field.name!r} of type {field.type.value} "

View on GitHub (pinned to 61d76f1ff3)

Solutions

1. Use the Python codec name for the code page: cp037 (US/Canada EBCDIC), cp500 (international #5), cp1026, cp1140... Check with python -c "import codecs; codecs.lookup('cp037')".
2. Validate the encoding before constructing the backend: codecs.lookup(name) in your own code so failures surface at config time.
3. Fix the layout file's encoding field to the Python-registered name.
4. Do not pass arbitrary 'EBCDIC-*' strings — resolve them to cpNNNN aliases first.

Example fix

# before
opts = EbcdicBackendOptions(encoding='EBCDIC-US')  # not a Python codec

# after
opts = EbcdicBackendOptions(encoding='cp037')  # US EBCDIC code page

import codecs

def valid_codec(name: str) -> bool:
    try:
        codecs.lookup(name)
        return True
    except LookupError:
        return False

assert valid_codec("cp037")       # ok
assert not valid_codec("EBCDIC-US")  # will fail -> fix config before converting

from docling.exceptions import DocumentLoadError
try:
    conv.convert(src, pipeline_options=opts)
except DocumentLoadError as e:
    if "Unknown EBCDIC codec" in str(e):
        opts.encoding = "cp037"  # map alias -> Python codec, then retry
        conv.convert(src, pipeline_options=opts)
    else:
        raise

When it happens

Trigger: Setting EbcdicBackendOptions(encoding='ebcdic-us') or another non-registered alias; a layout JSON/YAML whose encoding field carries a typo or vendor alias; building options from user input without validating the codec name.

Common situations: Copy-pasting IBM codec names (IBM-037, EBCDIC-US, ibm500) from mainframe documentation into the options; layout files authored from z/OS code pages; case or hyphen variants that are not Python codec aliases.

Related errors

• The EBCDIC backend needs a layout: set either EbcdicBackendO
• Could not read the EBCDIC layout {self.options.layout_file}.
• CsvDocumentBackend could not load document with hash {self.d
• Cannot decode field {field.name!r} of type {field.type.value
• No record layout matches record type {record_type!r}.

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