errors.json

{
  "$comment": "Machine-readable registry of zipnative's stable error codes (ZipErrorCode in src/types/zip-errors.ts) and diagnostic codes (ZipDiagnosticCode in src/types/zip-types.ts). Codes are frozen from 0.8.0: removal or renaming is semver-major; additions are semver-minor. The error-parity rule of scripts/verify-docs.ts enforces bidirectional sync with the source unions and class membership.",
  "package": "zipnative",
  "verifiedOn": "2026-10-08",
  "errors": [
    {
      "code": "ZIP_INVALID_OPTION",
      "class": "ZipError",
      "since": "0.8.0",
      "raisedWhen": "An option value fails validation: compression.level outside 0-9, a non-positive chunkSize, any zip64 value on a buffered entry (add(), addDirectory(), the modifier — only addStream() takes it), a malformed RawEntryMeta or a compression option for addRaw(), a directory entry carrying data, an extra-field block over 65 535 bytes, a Unix mode outside 0-0o177777, a ByteRangeSource whose size is not a non-negative integer, or an argument shape the API forbids.",
      "remedy": "Fix the option value at the call site — the message names the offending option and the accepted range."
    },
    {
      "code": "ZIP_INPUT_TOO_LARGE",
      "class": "ZipError",
      "since": "0.8.0",
      "raisedWhen": "The pure-TS deflate encoder received more than 2 GiB of input in one call.",
      "remedy": "Split the input, or stream it entry by entry."
    },
    {
      "code": "ZIP_ENTRY_NOT_FOUND",
      "class": "ZipError",
      "since": "0.8.0",
      "raisedWhen": "A named entry does not exist where one is required (readEntry and the other per-entry reads of openZip and openZipRange, replaceEntry, removeEntry, renameEntry, addFromReader).",
      "remedy": "Names are case-sensitive — iterate entries() to list what the archive holds."
    },
    {
      "code": "ZIP_ENTRY_EXISTS",
      "class": "ZipError",
      "since": "0.8.0",
      "raisedWhen": "A named entry already exists where absence is required (addEntry over an existing name; rename onto an existing name).",
      "remedy": "Use replaceEntry() to overwrite, or removeEntry() the target first — renames never overwrite implicitly."
    },
    {
      "code": "ZIP_API_MISUSE",
      "class": "ZipError",
      "since": "0.8.0",
      "raisedWhen": "A usage contract was violated: toBytes() with addStream() entries, drain-order violations in forward iteration, single-shot data()/skip() reuse, push() after an inflator finished.",
      "remedy": "The message names the contract and the compliant call sequence."
    },
    {
      "code": "ZIP_STRICT_DIAGNOSTIC",
      "class": "ZipError",
      "since": "0.8.0",
      "raisedWhen": "strict: true escalated the first conformance diagnostic of the operation into a thrown error.",
      "remedy": "The message embeds the underlying diagnostic code; handle the archive shape it names, or drop strict and receive diagnostics via onDiagnostic."
    },
    {
      "code": "ZIP_INTERNAL",
      "class": "ZipError",
      "since": "0.8.0",
      "raisedWhen": "An internal invariant broke — this is a zipnative bug, not an input problem. verifyZip() also reports any non-ZipError thrown while verifying under this code in report.error.",
      "remedy": "Report it with a reproduction archive or generator script."
    },
    {
      "code": "ZIP_EOCD_NOT_FOUND",
      "class": "ZipFormatError",
      "since": "0.8.0",
      "raisedWhen": "The input is smaller than 22 bytes, no end-of-central-directory record exists in the trailing scan window, or no candidate is self-consistent (trailing garbage / hostile ambiguity — zipnative refuses to guess).",
      "remedy": "The bytes are not a ZIP archive, are truncated, or carry trailing bytes — verify the source, or remove the trailing bytes if the archive is trusted."
    },
    {
      "code": "ZIP_EOCD_INCONSISTENT",
      "class": "ZipFormatError",
      "since": "0.8.0",
      "raisedWhen": "The end-of-central-directory record contradicts the archive layout: entries-on-disk differs from the total, or the central directory overlaps the record itself.",
      "remedy": "The archive is corrupt or hostile — re-obtain it from the source."
    },
    {
      "code": "ZIP_ZIP64_LOCATOR_MISSING",
      "class": "ZipFormatError",
      "since": "0.8.0",
      "raisedWhen": "A zip64 sentinel is set but the zip64 end-of-central-directory locator is absent.",
      "remedy": "The archive is truncated or corrupt — re-obtain it."
    },
    {
      "code": "ZIP_ZIP64_EOCD_MISPLACED",
      "class": "ZipFormatError",
      "since": "0.8.0",
      "raisedWhen": "The zip64 end-of-central-directory record is not where the locator points (and not at the fallback position). The byte-range reader (openZipRange) sizes its tail window for the APPNOTE layout, so a record placed far from its locator is reported with this code there too.",
      "remedy": "Corrupt archive, or an unsupported prepended-data layout — rebuild the archive without the prefix."
    },
    {
      "code": "ZIP_CD_INCONSISTENT",
      "class": "ZipFormatError",
      "since": "0.8.0",
      "raisedWhen": "The central-directory walk contradicts the declared counts or size: it ends early, a record extends past the declared size, or bytes remain beyond the declared entries.",
      "remedy": "The archive is corrupt or hostile — re-obtain it from the source."
    },
    {
      "code": "ZIP_RECORD_TRUNCATED",
      "class": "ZipFormatError",
      "since": "0.8.0",
      "raisedWhen": "A fixed or variable-length ZIP record (EOCD, zip64 EOCD, central or local header) or an entry's payload overruns the available bytes — including a byte-range source (openZipRange) whose declared size is smaller than the records imply or whose read() returns fewer bytes than requested.",
      "remedy": "The archive is truncated — verify the transfer completed."
    },
    {
      "code": "ZIP_SIGNATURE_MISMATCH",
      "class": "ZipFormatError",
      "since": "0.8.0",
      "raisedWhen": "An expected PK signature is absent: no local file header at the offset the central directory declares, no EOCD signature at the resolved offset, or a forward stream that does not start with a local header.",
      "remedy": "Check that the bytes are a ZIP archive (not a response body, an HTML error page or a different format) and re-obtain them; a truncated download shows the same way."
    },
    {
      "code": "ZIP_STREAM_TRUNCATED",
      "class": "ZipFormatError",
      "since": "0.8.0",
      "raisedWhen": "A forward byte stream ended mid-record or mid-entry (iterateZipEntries sources).",
      "remedy": "The stream was cut — verify the producer sent the complete archive."
    },
    {
      "code": "ZIP_VALUE_UNREPRESENTABLE",
      "class": "ZipFormatError",
      "since": "0.8.0",
      "raisedWhen": "A 64-bit field exceeds Number.MAX_SAFE_INTEGER (2^53 - 1).",
      "remedy": "Split the content into archives under 2^53 bytes (about 9 PB); the public API uses number, not bigint, by design."
    },
    {
      "code": "ZIP_INVALID_ENTRY_NAME",
      "class": "ZipFormatError",
      "since": "0.8.0",
      "raisedWhen": "A writer-side entry name violates the name rules: empty, NUL bytes, backslashes, absolute paths, or '..' segments (zipnative never writes traversal-capable archives).",
      "remedy": "Use relative, forward-slash paths without traversal segments."
    },
    {
      "code": "ZIP_DUPLICATE_ENTRY_NAME",
      "class": "ZipFormatError",
      "since": "0.8.0",
      "raisedWhen": "Duplicate entry names where uniqueness is required: add() over an existing name, or opening a duplicate-name archive with createZipModifier().",
      "remedy": "Every archive path must be unique; for duplicate-name source archives, extract and rebuild with createZip()."
    },
    {
      "code": "ZIP_DEFLATE_TRUNCATED",
      "class": "ZipFormatError",
      "since": "0.8.0",
      "raisedWhen": "A deflate stream ends mid-block: the data ran out before the final block completed. Raised on every tier since 1.1.0 — the pure-TS inflater and node:zlib (Z_BUF_ERROR) distinguish truncation; a DecompressionStream outside Node reports no cause, so its failures surface as ZIP_DEFLATE_CORRUPT.",
      "remedy": "The compressed payload is truncated — re-obtain the archive."
    },
    {
      "code": "ZIP_DEFLATE_CORRUPT",
      "class": "ZipFormatError",
      "since": "0.8.0",
      "raisedWhen": "A deflate stream is structurally invalid: bad Huffman codes, invalid symbols, out-of-range back-references, LEN/NLEN mismatches, or an unsupported block type. Raised on every tier since 1.1.0 — node:zlib (Z_DATA_ERROR, Z_NEED_DICT) and DecompressionStream failures are normalised to this code.",
      "remedy": "The compressed payload is corrupt — re-obtain the archive."
    },
    {
      "code": "ZIP_ENTRY_OVERLAP",
      "class": "ZipSecurityError",
      "since": "0.8.0",
      "cwe": "CWE-405",
      "raisedWhen": "Two entries share bytes: duplicate local-header offsets, an entry extending into another, or an entry claiming to start inside the central directory. The lazy reader checks the local-header signature first, so for the last shape a lazy readEntry() may report ZIP_SIGNATURE_MISMATCH where validate: 'eager' and verifyZip() report this code.",
      "remedy": "Rebuild the archive with a conformant tool (or saveCompact() from a trusted copy); overlapping-entry archives are a decompression-bomb/smuggling shape and are always rejected — there is no opt-out."
    },
    {
      "code": "ZIP_CD_LFH_MISMATCH",
      "class": "ZipSecurityError",
      "since": "0.8.0",
      "cwe": "CWE-436",
      "raisedWhen": "A local file header contradicts the central directory on the compression method.",
      "remedy": "Parser-differential archives are rejected — rebuild the archive with a sane tool."
    },
    {
      "code": "ZIP_ZIP64_CONTRADICTION",
      "class": "ZipSecurityError",
      "since": "0.8.0",
      "cwe": "CWE-1288",
      "raisedWhen": "A zip64 value contradicts a non-sentinel classic field (zip64 may only REPLACE sentinel fields).",
      "remedy": "Parser-differential archives are rejected — rebuild the archive."
    },
    {
      "code": "ZIP_PATH_TRAVERSAL",
      "class": "ZipSecurityError",
      "since": "0.8.0",
      "cwe": "CWE-22/CWE-67",
      "raisedWhen": "An entry name cannot be made safe: it escapes the extraction root (zip-slip — '..' segments, absolute paths, drive letters, UNC prefixes, backslash tricks, NTFS alternate data streams) or is a Windows reserved device name (CON, NUL, COM1..LPT9).",
      "remedy": "The archive is hostile, corrupt, or POSIX-authored with device-name files; pass rejectTraversal: false to silently skip such entries instead (they are never emitted)."
    },
    {
      "code": "ZIP_SYMLINK_REJECTED",
      "class": "ZipSecurityError",
      "since": "0.8.0",
      "cwe": "CWE-59",
      "raisedWhen": "An entry is a Unix symlink and rejectSymlinks is on (the default).",
      "remedy": "Pass rejectSymlinks: false to receive the link target as ordinary data (never materialized as a link)."
    },
    {
      "code": "ZIP_EXTRACT_DUPLICATE_PATH",
      "class": "ZipSecurityError",
      "since": "0.8.0",
      "cwe": "CWE-694",
      "raisedWhen": "Two entries resolve to the same output path under onDuplicate: 'error' (the default).",
      "remedy": "Pass onDuplicate: 'first' or 'last' to resolve the shadowing deliberately."
    },
    {
      "code": "ZIP_CRC_MISMATCH",
      "class": "ZipDataError",
      "since": "0.8.0",
      "raisedWhen": "Decompressed bytes fail the declared CRC-32 (central directory, local header, or data descriptor).",
      "remedy": "The data is corrupt; expectedCrc/actualCrc carry both values. Pass verifyCrc: false only if you accept corrupt output (addFromReader: verify: false copies the entry unchecked)."
    },
    {
      "code": "ZIP_SIZE_MISMATCH",
      "class": "ZipDataError",
      "since": "0.8.0",
      "raisedWhen": "Sizes contradict: the decompressed size differs from the declared size, or local-header sizes/CRC contradict the central directory.",
      "remedy": "The archive metadata lies — treat the archive as corrupt or hostile (addFromReader: verify: false copies the entry unchecked)."
    },
    {
      "code": "ZIP_INFLATE_OUTPUT_OVERFLOW",
      "class": "ZipDataError",
      "since": "0.8.0",
      "raisedWhen": "Inflate produced more output than the declared or permitted bound.",
      "remedy": "The archive metadata lies about this entry, or raise the relevant limit if the archive is trusted."
    },
    {
      "code": "ZIP_DESCRIPTOR_MISMATCH",
      "class": "ZipDataError",
      "since": "0.8.0",
      "raisedWhen": "No data-descriptor form (signed/signless × 32/64-bit) matches the measured CRC and sizes of a bit-3 entry.",
      "remedy": "The stream is corrupt or hostile — use openZip() on the complete archive for the authoritative view."
    },
    {
      "code": "ZIP_DECOMPRESSION_FAILED",
      "class": "ZipDataError",
      "since": "0.8.0",
      "raisedWhen": "A codec registered with registerCodec() or injected with setInflateImpl() threw mid-decompression. Since 1.1.0 the built-in deflate tiers never raise it: their failures are ZIP_DEFLATE_CORRUPT, ZIP_DEFLATE_TRUNCATED or ZIP_INFLATE_OUTPUT_OVERFLOW on every tier.",
      "remedy": "The data is corrupt or hostile, or the injected codec is faulty — the wrapped detail is in the message."
    },
    {
      "code": "ZIP_LIMIT_EXCEEDED",
      "class": "ZipLimitError",
      "since": "0.8.0",
      "cwe": "CWE-400/CWE-409",
      "fields": "limit (the ZipLimits key), configured, observed",
      "raisedWhen": "A configured security bound from ZipLimits was exceeded.",
      "remedy": "Raise limits.<limit> explicitly if this archive is trusted — the message names the key and both values."
    },
    {
      "code": "ZIP_LIMIT_INVALID",
      "class": "ZipLimitError",
      "since": "0.8.0",
      "fields": "limit (the offending key), configured = observed = NaN",
      "raisedWhen": "The limits override itself is invalid: an unknown key, or a non-positive/NaN value.",
      "remedy": "Fix the limits object at the call site — valid keys are listed in the message."
    },
    {
      "code": "ZIP_UNSUPPORTED_ENCRYPTION",
      "class": "ZipUnsupportedError",
      "since": "0.8.0",
      "feature": "zipcrypto | aes | strong-encryption",
      "raisedWhen": "An entry is encrypted — ZipCrypto (bit 0), WinZip AES (method 99 or the 0x9901 extra field, labelled feature 'aes' since 1.1.0) or strong encryption (bit 6). Encryption is unsupported in 1.x by policy; AES is a 2.0 candidate.",
      "remedy": "Check entry.isEncrypted to route around such entries; encrypted entries remain copyable by the modifier without decompression."
    },
    {
      "code": "ZIP_UNSUPPORTED_METHOD",
      "class": "ZipUnsupportedError",
      "since": "0.8.0",
      "feature": "method:<n>",
      "raisedWhen": "An entry uses a compression method with no registered codec.",
      "remedy": "registerCodec() one, or re-save the archive with store/deflate."
    },
    {
      "code": "ZIP_UNSUPPORTED_MULTI_DISK",
      "class": "ZipUnsupportedError",
      "since": "0.8.0",
      "feature": "multi-disk",
      "raisedWhen": "The archive is multi-disk/spanned (EOCD disk fields, zip64 locator disk count, or an entry starting on another disk).",
      "remedy": "Multi-disk archives are an explicit anti-goal — rebuild as a single archive."
    },
    {
      "code": "ZIP_UNSUPPORTED_ZIP64_STREAMING",
      "class": "ZipUnsupportedError",
      "since": "0.8.0",
      "feature": "zip64-streaming",
      "raisedWhen": "An addStream() entry crosses 4 GiB without the per-entry Zip64 opt-in — the classic streaming layout cannot represent it, and the refusal happens before the crossing chunk is emitted.",
      "remedy": "Pass { zip64: true } to addStream() for entries that may exceed 4 GiB (Zip64 local header, 24-byte descriptor — 1.1.0), buffer the content via add(), or split it."
    },
    {
      "code": "ZIP_UNSUPPORTED_CD_LESS_DESCRIPTOR",
      "class": "ZipUnsupportedError",
      "since": "0.8.0",
      "feature": "cd-less-descriptor",
      "raisedWhen": "Forward reading met a data-descriptor (bit 3) entry whose payload cannot be delimited without the central directory: any method other than deflate (store, a registered codec) or an encrypted entry — only the resumable deflate decoder reports exactly where the payload ends.",
      "remedy": "Use openZip() on the complete archive instead."
    },
    {
      "code": "ZIP_UNSUPPORTED_CODEC_MODE",
      "class": "ZipUnsupportedError",
      "since": "0.8.0",
      "feature": "method:<n>",
      "raisedWhen": "A registered codec supports only the other access mode: stream-only codecs via readEntry(), codecs without a streaming decompressor via readEntryStream(); and, since 1.1.0, the forward reader (iterateZipEntries) refuses — before the first byte — a codec for a method other than store/deflate that does not expose createDecompressor(), as does the byte-range reader (openZipRange): its readEntry() needs decompressSync, its readEntryStream() needs createDecompressor() or decompressStream (a decompressSync-only codec is refused with this code — use readEntry()).",
      "remedy": "The message names the compliant call (readEntryStream() or readEntry()); in the forward reader, skip() the entry or open the complete archive with openZip(); for your own codec, implement createDecompressor()."
    }
  ],
  "diagnostics": [
    {
      "code": "ZIP_PREPENDED_DATA",
      "severity": "info",
      "raisedWhen": "Bytes precede the archive (self-extractor stub or concatenation); all offsets were shifted accordingly.",
      "remedy": "Verify the prefix is expected for this file."
    },
    {
      "code": "ZIP_MULTIPLE_EOCD",
      "severity": "info",
      "raisedWhen": "More than one end-of-central-directory signature exists; the last self-consistent candidate was used.",
      "remedy": "Expected for archives whose comment embeds the signature; otherwise inspect the file."
    },
    {
      "code": "ZIP_NAME_MISMATCH",
      "severity": "warning",
      "raisedWhen": "A local header's filename bytes differ from the central directory's; the central directory wins.",
      "remedy": "Rebuild the archive with a sane tool if the divergence is unexpected."
    },
    {
      "code": "ZIP_UNICODE_PATH_CONFLICT",
      "severity": "warning",
      "raisedWhen": "The 0x7075 Unicode Path extra field disagrees with the header name; the header name wins (0x7075 is never acted on).",
      "remedy": "None needed — informational about the producer's inconsistency."
    },
    {
      "code": "ZIP_INVALID_UTF8_NAME",
      "severity": "warning",
      "raisedWhen": "Flag bit 11 claims UTF-8 but the name bytes are invalid UTF-8; decoded as CP437 instead.",
      "remedy": "The producer lied about the encoding — verify names look right."
    },
    {
      "code": "ZIP_DUPLICATE_NAME",
      "severity": "warning",
      "raisedWhen": "The central directory holds duplicate entry names; getEntry() returns the last.",
      "remedy": "Iterate entries() to see every duplicate; extraction under onDuplicate: 'error' throws."
    },
    {
      "code": "ZIP_EXTRA_FIELD_MALFORMED",
      "severity": "warning",
      "raisedWhen": "An extra field overruns its declared length and was skipped.",
      "remedy": "None needed — the malformed field is ignored, the rest is parsed."
    },
    {
      "code": "ZIP_ZIP64_EXTRA_IGNORED",
      "severity": "warning",
      "raisedWhen": "A zip64 extra supplied a value for a non-sentinel classic field; the header value wins.",
      "remedy": "Producer inconsistency — rebuild if unexpected."
    },
    {
      "code": "ZIP_TIMESTAMP_NOT_PINNED",
      "severity": "info",
      "raisedWhen": "defaultDate: 'now' makes the output non-reproducible.",
      "remedy": "Pin a Date (or accept the DOS-epoch default) for deterministic bytes."
    },
    {
      "code": "ZIP_NONDETERMINISTIC_CODEC",
      "severity": "info",
      "raisedWhen": "Timestamps are pinned but a platform codec is in use — bytes are stable per environment, not across zlib builds.",
      "remedy": "Pass deterministic: true to pin the pure-TS encoder for cross-runtime identical bytes."
    },
    {
      "code": "ZIP_DEAD_BYTES_RATIO",
      "severity": "info",
      "raisedWhen": "An incremental save() left more than 50% dead bytes; removed/replaced content remains recoverable in the file.",
      "remedy": "Use saveCompact() for true deletion and a canonical layout."
    },
    {
      "code": "ZIP_TIMESTAMP_CLAMPED",
      "severity": "info",
      "since": "1.1.0",
      "raisedWhen": "A Date passed as defaultDate or an entry date is invalid, before 1980-01-01 or after 2107-12-31 23:59:58; the DOS epoch (or the maximum) was written instead of a fictitious in-range date. Since 1.1.0.",
      "remedy": "Pass a Date within 1980-2107 (dosTimeMode selects the wall-clock it is read with), or omit it for the deterministic epoch default."
    }
  ],
  "sink": {
    "errors": "Thrown; every message starts 'zipnative: ' and names the remedy; err.code is the stable machine key, err.name/instanceof give the class.",
    "diagnostics": "console.warn deduplicated per code per operation by default; onDiagnostic receives all; strict: true throws ZipError code ZIP_STRICT_DIAGNOSTIC."
  }
}