Error codes¶

Every error raised by mrrc carries a stable identifier (Exxx) and a human-friendly slug. Match on the code rather than the exception class name to keep handlers stable across enum restructures, and follow the help URL to land here.

import mrrc

try:
    list(mrrc.MARCReader("harvest.mrc", recovery_mode="strict",
                         validation_level="strict_marc"))
except mrrc.MrrcException as e:
    print(e.code, e.slug, e.help_url())
    # E201 invalid_indicator https://mrrc.dev/reference/error-codes/#E201

match err {
    e if e.code() == "E201" => handle_indicator_error(e),
    _ => return Err(e),
}

Configuring the help URL base¶

By default err.help_url() returns a URL anchored to this page hosted on GitHub Pages (https://dchud.github.io/mrrc/reference/error-codes/). Enterprise deployments that mirror the docs internally can redirect the help URL by setting the MRRC_DOCS_BASE_URL environment variable to their docs root. Both the Rust core and the Python bindings honor it:

export MRRC_DOCS_BASE_URL="https://docs.example.com/mrrc"
# err.help_url() → "https://docs.example.com/mrrc/reference/error-codes/#E201"

The variable holds the docs site root; the /reference/error-codes/#Exxx path is appended automatically. Trailing slashes are stripped.

Stability¶

Two rules, non-negotiable:

Codes never get re-purposed. A retired check leaves its docs entry in place pointing to a replacement.
Codes never get renumbered. URLs that users paste into chat have to keep resolving.

See Adding a code below for the procedure when introducing a new code.

Code ranges¶

Range	Phase
`E0xx`	Stream / leader
`E1xx`	Directory / field header
`E2xx`	Subfield / indicator
`E3xx`	Encoding
`E4xx`	Serialization / writer
`Wxxx`	Warnings (pymarc parity)

Each range reserves ~80 slots for future growth.

Adding a code¶

Pick the next available number in the appropriate range (see Code ranges above).
Add a ## Exxx — \slug` { #Exxx }` section to this file with the full entry shape (Context, Applies to, Populates, Common causes, How to recover, Python class).
Add the variant's code() and slug() arms in src/error.rs.
Add the matching code / slug class constants on the Python exception class in mrrc/exceptions.py.
Add the (class, code, slug) tuple to _CODE_TABLE in tests/python/test_errors.py so the unique-codes / unique-slugs assertions catch any duplicates.
Add a CHANGELOG.md entry under [Unreleased] listing the new code.

Stream / leader (E0xx)¶

E001 — `record_length_invalid`¶

The leader's record-length field (bytes 0–4) is invalid: not five ASCII digits, or claims a length below the 24-byte minimum.

Context: Parse-side. Applies to: Bibliographic, Authority, Holdings readers. Populates: record_index, byte_offset. May also populate: source.

Common causes. Truncated download; reader fed text instead of binary; attempt to parse a non-MARC file by accident.

How to recover. Verify the input is binary MARC (file usually has a .mrc extension and starts with five ASCII digits). No recovery mode salvages this — the next 24 bytes can't be trusted as a leader.

Python class: mrrc.RecordLengthInvalid.

E002 — `leader_invalid`¶

The 24-byte leader is malformed in a way other than the record-length or base-address fields. Two failure shapes share this code:

Structural (always fires): byte-level malformation — e.g., the indicator-count byte (position 10) is not an ASCII digit, or the reserved bytes 20–23 are not 4500. Detected during Leader::from_bytes regardless of validation_level.
MARC 21 semantics (fires only at validation_level="strict_marc"): the leader parses cleanly but a position carries a value not in the MARC 21 allowed set — e.g., record_status (position 5) outside {a, c, d, n, p}, record_type (position 6) outside the documented set, indicator_count not equal to 2, encoding_level outside the allowed set, etc.

The MARC 21 allowed-value sets at the per-position level differ by reader type. The bibliographic, authority, and holdings readers each apply their own format's spec at strict_marc:

Bibliographic (MarcReader): the union of positions defined in the MARC 21 Bibliographic Format leader — positions 5–11 and 17–19.
Authority (AuthorityMarcReader): the MARC 21 Authority Format allowed sets. Positions 7 (bibliographic_level), 8 (control_record_type), and 19 (multipart_level) are undefined for authority records and accept any byte (including the MARC 21 fill character |). Position 5 accepts the wider set {a, c, d, n, o, s, x}, position 6 must be z, position 17 must be n or o, and position 18 carries the punctuation policy allowed set {space, c, i, u} instead of the bibliographic "cataloging form" set.
Holdings (HoldingsMarcReader): the MARC 21 Holdings Format allowed sets. Positions 7, 8, and 19 are undefined as for authority. Position 5 accepts {c, d, n}, position 6 accepts {u, v, x, y}, position 17 (encoding level) accepts {1, 2, 3, 4, 5, m, u, z}, and position 18 (item information in record) accepts {space, i, n}.

A leader that is valid per one record type's format may be invalid per another's (e.g., encoding_level='1' is valid for bibliographic but invalid for authority).

Context: Parse-side. Applies to: Bibliographic, Authority, Holdings readers. Populates: record_index, byte_offset, record_byte_offset (= 0). May also populate: source, found, expected.

Common causes. Records hand-crafted in a text editor and saved in the wrong encoding; output from non-conformant exporters; pre-2000s records using deprecated leader values.

How to recover. Structural shape (1) fires before any field parsing and is not affected by recovery_mode. The MARC 21 semantic shape (2) respects recovery_mode: in lenient/permissive the violation is attached to the yielded record's record.errors list and parsing continues; in strict it raises immediately. To suppress (2) entirely, use the default validation_level="structural".

Python class: mrrc.RecordLeaderInvalid.

E003 — `base_address_invalid`¶

The leader's base-address-of-data field (bytes 12–16) is not five ASCII digits or claims a value below 25.

Context: Parse-side. Applies to: Bibliographic, Authority, Holdings readers. Populates: record_index, byte_offset. May also populate: source, record_control_number, found, expected.

Common causes. Records written by older systems that miscalculate the directory length; corrupted bytes 12–16 from in-flight data damage.

How to recover. Not recoverable; the directory boundary can't be inferred without the base address.

Python class: mrrc.BaseAddressInvalid.

E004 — `base_address_not_found`¶

The leader claims a base address of data that exceeds the available bytes in the input stream.

Context: Parse-side. Applies to: Bibliographic, Authority, Holdings readers. Populates: record_index, byte_offset. May also populate: source, record_control_number.

Common causes. Truncated input; record header damaged so the length/base-address pair are inconsistent.

How to recover. See E005 for the related truncation case.

Python class: mrrc.BaseAddressNotFound.

E005 — `truncated_record`¶

The reader hit EOF before reading the number of bytes the leader claims the record should contain.

Context: Parse-side. Applies to: Bibliographic, Authority, Holdings readers. Populates: record_index, byte_offset, record_byte_offset, expected_length, actual_length. May also populate: source, record_control_number.

Common causes. Network read truncated by connection drop; partially- written file from a crashed exporter; deliberate fuzzing.

How to recover. recovery_mode="lenient" salvages whatever fields parsed cleanly before the truncation point. recovery_mode="strict" raises this error immediately.

Python class: mrrc.TruncatedRecord (subclass of mrrc.EndOfRecordNotFound).

E006 — `end_of_record_not_found`¶

The end-of-record byte (0x1D) was not found at the position the leader implied.

Context: Parse-side. Applies to: Bibliographic, Authority, Holdings readers. Populates: record_index, byte_offset, record_byte_offset. May also populate: source, record_control_number.

Common causes. Concatenated records where one was truncated mid- stream; corrupted bytes near the end of a record; encoder bugs.

How to recover. recovery_mode="lenient" accepts the partial record and continues reading from the next leader.

Python class: mrrc.EndOfRecordNotFound. Also catches E005 (TruncatedRecord is a subclass).

E007 — `io_error`¶

An I/O error occurred reading from the underlying source.

Context: Parse-side (or anywhere I/O can fail). Applies to: All readers. Populates: cause (the underlying std::io::Error). May also populate: record_index, byte_offset, source.

Common causes. File permissions; broken pipe; network read failure; disk error.

How to recover. Inspect e.__cause__ for the underlying I/O kind. Non-recoverable in general; the caller decides whether to retry.

Python class: raised as Python's built-in OSError (via IOError) rather than a typed mrrc class — matches pymarc behavior. Catch OSError to handle alongside other I/O errors.

E099 — `fatal_reader_error`¶

A fatal condition halted the reader. Currently raised when the per-stream recovered-error cap is exceeded in RecoveryMode::Lenient or Permissive — see MarcReader::with_max_errors. The code is reserved for future fatal-reader scenarios as well.

Context: Parse-side, lenient/permissive only. Strict mode aborts on the first error, so this code never fires there. Applies to: MarcReader, AuthorityMarcReader (the holdings reader exposes the builder for parity but has no active recovery sites today). Populates: cap (the configured limit) and errors_seen (count at the moment of the trip). May also populate: record_index, source.

Common causes. Feeding a pathological stream (mostly-malformed records) through a lenient/permissive reader. Without the cap the accumulated per-record diagnostics could exhaust memory.

How to recover. If the cap is a false positive for the input, raise it (reader.with_max_errors(n) with a larger n, or 0 to disable). If it reflects the actual state of the input, investigate the source — large counts of recovered errors usually indicate upstream corruption.

After this error is raised the reader is exhausted; subsequent read_record() calls return Ok(None).

Directory / field header (E1xx)¶

E101 — `directory_invalid`¶

A directory entry (12 bytes: 3-byte tag + 4-byte length + 5-byte start position) is structurally invalid: bad tag bytes, non-numeric length or start, or claimed field bytes extending past the data area.

Context: Parse-side. Applies to: Bibliographic, Authority, Holdings readers. Populates: record_index, byte_offset, record_byte_offset. May also populate: field_tag (when the bad entry's tag was decodable), record_control_number, source, found, expected.

Common causes. Encoder bugs; corrupted bytes; legacy records with non-standard tag formats.

How to recover. recovery_mode="lenient" skips the bad entry and continues parsing the rest of the directory.

Python class: mrrc.RecordDirectoryInvalid. Also catches E106, E201, E202 (subclasses).

E105 — `field_not_found`¶

A requested field was not present in the parsed record. This is an accessor error, not a parse error — it surfaces when code calls e.g. record.get_field("245") and the record doesn't contain that tag.

Context: Accessor (post-parse). Applies to: All record types. Populates: field_tag. May also populate: record_control_number, record_index. Never populates: byte_offset (not a parse error).

Common causes. Calling a get_field on records that don't have the tag; programming error or assumption about input shape.

How to recover. Use try/except or check field in record first.

Python class: mrrc.FieldNotFound.

E106 — `invalid_field`¶

A data field is structurally invalid in a way not covered by the more specific E201 / E202 subclasses (e.g., field bytes too short for indicators, field declared length exceeds available bytes).

Context: Parse-side. Applies to: Bibliographic, Authority, Holdings readers. Populates: record_index, byte_offset, record_byte_offset, field_tag. May also populate: record_control_number, source. The message attribute carries a human-readable description of the problem.

Common causes. Encoder dropped subfields; declared field length inconsistent with actual data.

How to recover. recovery_mode="lenient" skips the bad field and continues with the rest.

Python class: mrrc.InvalidField (subclass of mrrc.RecordDirectoryInvalid).

Subfield / indicator (E2xx)¶

E201 — `invalid_indicator`¶

A variable-data field's indicator byte is not a valid value for the given tag. Two failure shapes are reported under this code at validation_level="strict_marc":

Byte-level: the indicator byte is not an ASCII digit (0-9) or space. expected is "ASCII digit (0-9) or space".
Per-tag MARC 21 semantics: the byte passes (1) but violates the per-tag rule for the field. For example, the first indicator of 245 (Title statement) is restricted to 0 or 1 per MARC 21; a 9 is byte-valid but tag-invalid. expected describes the tag-specific rule (e.g., "'0' or '1'", "digit 0-9").

The two shapes share an error code because they share a position (field_tag, indicator_position) and a remedy (fix the indicator); they differ only in the expected string.

Context: Parse-side. Applies to: Bibliographic, Authority, Holdings readers — fired uniformly when validation_level="strict_marc". At the default validation_level="structural" indicator bytes are accepted as-is and this code does not fire. Populates: record_index, byte_offset, record_byte_offset, field_tag, indicator_position, found, expected. May also populate: record_control_number, source.

Common causes. Source systems emitting local-use indicators; records round-tripped through non-conformant ILSes; sloppy cataloging from pre-2000s records.

How to recover. Use validation_level="structural" (default) to accept the bytes silently, or recovery_mode="lenient" to keep iterating past the offending record under strict_marc.

Python class: mrrc.InvalidIndicator (subclass of mrrc.RecordDirectoryInvalid).

E202 — `bad_subfield_code`¶

A subfield code byte (immediately following a 0x1F delimiter) is not a printable ASCII character.

Context: Parse-side. Applies to: Bibliographic, Authority, Holdings readers — fired uniformly when validation_level="strict_marc". At the default validation_level="structural" subfield-code bytes are accepted as-is and this code does not fire. Populates: record_index, byte_offset, record_byte_offset, field_tag, subfield_code (the offending byte). May also populate: record_control_number, source.

Common causes. Bytes corrupted near a subfield boundary; encoder emitting non-ASCII codes for local-use subfields.

How to recover. Use validation_level="structural" (default) to accept the bytes silently, or recovery_mode="lenient" to keep iterating past the offending record under strict_marc.

Python class: mrrc.BadSubfieldCode (subclass of mrrc.RecordDirectoryInvalid).

Encoding (E3xx)¶

E301 — `utf8_invalid`¶

A subfield value or control field in a record decoded as UTF-8 contains bytes that are not valid UTF-8. A record is decoded as UTF-8 when its leader position 09 is a, or when the reader's character_coding says so (see Character encoding).

Context: Parse-side (or wherever a string conversion runs). Applies to: Bibliographic, authority, and holdings readers — fired uniformly, at every validation level, when a value contains bytes that aren't valid UTF-8 under the default utf8_handling="strict" (Rust: Utf8Handling::Strict), as pymarc's default does. utf8_handling="replace" substitutes U+FFFD and "ignore" drops the bytes; neither surfaces this code. Populates: record_index. May also populate: field_tag, byte_offset, source, record_control_number. The message attribute carries the underlying std::str::Utf8Error description.

Common causes. Records cataloged in MARC-8 encoding without correct character-coding leader byte; legacy records with embedded byte sequences that are valid in MARC-8 but not in UTF-8.

How to recover. Pass utf8_handling="replace" to accept U+FFFD substitutions, or "ignore" to drop the invalid bytes. Under the default recovery mode, the field holding the bad bytes is dropped and the error recorded on record.errors. Convert input to UTF-8 before parsing if you need byte-perfect fidelity.

Python class: mrrc.EncodingError.

E302 — `marc8_invalid`¶

A subfield value or control field in a record decoded as MARC-8 contains a character with no mapping in the active MARC-8 character set, or an escape sequence cut off by the end of the value.

Context: Parse-side (or wherever a string conversion runs). Applies to: Bibliographic, authority, and holdings readers — fired uniformly when validation_level="strict_marc" and a MARC-8 value doesn't decode. At the default validation_level="structural" each undecodable character becomes U+FFFD and this code isn't surfaced (pymarc substitutes a space and never raises). Populates: record_index. May also populate: field_tag, byte_offset, source, record_control_number. The message attribute says how many characters could not be decoded and in which field.

Common causes. A record whose leader position 09 says MARC-8 (any value other than a) but whose data is UTF-8 or another encoding; MARC-8 data damaged in transfer, such as a truncated escape sequence; bytes from a vendor-specific character set.

How to recover. If the data is really UTF-8, read with character_coding="utf-8" (pymarc's force_utf8=True), or with character_coding="detect" when a file mixes MARC-8 and UTF-8 records. Set validation_level="structural" to accept U+FFFD substitutions.

Python class: mrrc.Marc8Error, a subclass of mrrc.EncodingError, so except mrrc.EncodingError: catches both E301 and E302.

Serialization / writer (E4xx)¶

E401 — `marcxml_invalid`¶

A MARCXML document failed to parse.

Context: Parse-side (XML parser layer). Applies to: mrrc.marcxml_to_record / marcxml_to_records. Populates: cause (the underlying quick_xml error). May also populate: record_index, byte_offset (when the parser exposes a position), source. The message attribute carries the parser's diagnostic.

Common causes. Malformed XML (unclosed tags, invalid characters); namespace-prefix mismatch; non-MARCXML XML where MARCXML was expected.

How to recover. Inspect e.__cause__ for the parser's specific error. The bytes can't be re-parsed without correction.

Python class: mrrc.XmlError.

E402 — `marcjson_invalid`¶

A MARCJSON document failed to parse.

Context: Parse-side (JSON parser layer). Applies to: mrrc.marcjson_to_record, mrrc.json_to_record. Populates: cause (the underlying serde_json::Error with line() and column() available). May also populate: record_index, byte_offset, source.

Common causes. Truncated JSON; mixed text encodings; non-MARCJSON JSON where MARCJSON was expected.

How to recover. Inspect e.__cause__.line and .column for the position; re-encode the input or fix upstream.

Python class: mrrc.JsonError.

E404 — `record_too_large_for_iso2709`¶

The writer attempted to serialize a record whose total length or base- address-of-data exceeds the ISO 2709 5-digit limit (99999 bytes for length, same for base address).

Context: Writer-side. Applies to: MARCWriter, AuthorityMarcWriter, HoldingsMarcWriter. Populates: record_index, record_control_number. The message attribute names which limit was exceeded with the actual byte count. Never populates: byte_offset (this fires before any bytes are written).

Common causes. Records with very large fields (full-text content in 505 or 520); aggregations of records with many repeated fields.

How to recover. Split the record into smaller units; use a different serialization format (MARCXML or MARCJSON) that doesn't have the 5-digit length limit.

Python class: mrrc.WriterError.

Warnings (Wxxx)¶

W001 — `bad_subfield_code_warning`¶

A subfield code is unusual but the field is otherwise valid (pymarc compatibility — pymarc raises this as a UserWarning).

Context: Warning during parsing; does not abort the parse. Python class: mrrc.BadSubfieldCodeWarning (a UserWarning, not an exception).

Error codes¶

Configuring the help URL base¶

Stability¶

Code ranges¶

Adding a code¶

Stream / leader (E0xx)¶

E001 — record_length_invalid¶

E002 — leader_invalid¶

E003 — base_address_invalid¶

E004 — base_address_not_found¶

E005 — truncated_record¶

E006 — end_of_record_not_found¶

E007 — io_error¶

E099 — fatal_reader_error¶

Directory / field header (E1xx)¶

E101 — directory_invalid¶

E105 — field_not_found¶

E106 — invalid_field¶