What causes "Invalid ZIP archive: missing ZIP64 extra field" in can1357/oh-my-pi?

Re-obtain the archive and verify its integrity (unzip -t, 7z t).

can1357/oh-my-pi · error · ArchiveError

Invalid ZIP archive: missing ZIP64 extra field

Error message

Invalid ZIP archive: missing ZIP64 extra field

What it means

A ZIP entry uses ZIP64 placeholders (0xFFFFFFFF sizes/offset or 0xFFFF disk number), meaning the real values must come from a ZIP64 extra field (id 0x0001), but no such extra field exists in the entry's extra data. The archive is inconsistent: it declares ZIP64 encoding without supplying the actual 64-bit values, so the library cannot resolve the real sizes or offsets.

Source

Thrown at packages/utils/src/ar/zip.ts:304

			result.mtimeMs = parseNtfsMtime(data);
		}
		offset = dataEnd;
	}
	return result;
}

function applyZip64Values(
	extra: Uint8Array | undefined,
	current: Zip64Values,
	placeholders: Zip64Placeholders,
): Zip64Values {
	const needs =
		placeholders.uncompressedSize ||
		placeholders.compressedSize ||
		placeholders.localHeaderOffset ||
		placeholders.diskStart;
	if (!needs) return current;
	if (!extra) throw new ArchiveError("Invalid ZIP archive: missing ZIP64 extra field");
	let offset = 0;
	const result = { ...current };
	if (placeholders.uncompressedSize) {
		if (offset + 8 > extra.byteLength) throw new ArchiveError("Invalid ZIP archive: malformed ZIP64 extra field");
		result.uncompressedSize = readUInt64LE(extra, offset);
		offset += 8;
	}
	if (placeholders.compressedSize) {
		if (offset + 8 > extra.byteLength) throw new ArchiveError("Invalid ZIP archive: malformed ZIP64 extra field");
		result.compressedSize = readUInt64LE(extra, offset);
		offset += 8;
	}
	if (placeholders.localHeaderOffset) {
		if (offset + 8 > extra.byteLength) throw new ArchiveError("Invalid ZIP archive: malformed ZIP64 extra field");
		result.localHeaderOffset = readUInt64LE(extra, offset);
		offset += 8;
	}
	if (placeholders.diskStart) {

View on GitHub (pinned to 9690622007)

Solutions

Re-obtain the archive and verify its integrity (unzip -t, 7z t).
Repack the archive with a conformant tool (7z, Info-ZIP zip, Python zipfile) so ZIP64 records are emitted correctly.
If your writer produces this, emit a ZIP64 extra field (id 0x0001) with 8-byte uncompressed size, 8-byte compressed size, 8-byte offset, 4-byte disk whenever placeholders are used.

Example fix

// producer bug: setting placeholder but dropping extra field
// after
// extra = Buffer.concat([extra, zip64Extra({uncompressedSize, compressedSize, localHeaderOffset, diskStart})]);

Defensive patterns

Strategy: validation

Validate before calling

import { $ } from "bun";
const probe = await $`unzip -v archive.zip`.quiet().nothrow();
if (probe.exitCode !== 0) throw new Error("ZIP64 archive is malformed; refusing to parse");

Try / catch

try {
  await archive.readMember(path);
} catch (err) {
  if (err instanceof ArchiveError && err.message.includes("missing ZIP64 extra field")) {
    throw new Error(`Archive ${zipPath} is corrupt (ZIP64 values absent); re-obtain it`);
  } else throw err;
}

Prevention

Keep an original copy of large archives; >4GB files are ZIP64 and more fragile to third-party rewriters.
Avoid tools that strip extra fields when post-processing ZIP64 archives.
Validate with 7z t before ingestion.

When it happens

Trigger: Calling a ZIP read/list API on an entry whose central-directory record has placeholder values (uncompressedSize/compressedSize/localHeaderOffset == 0xFFFFFFFF or diskStart == 0xFFFF) while its extra field list contains no 0x0001 record.

Common situations: Archives produced by broken ZIP64 implementations, archives post-processed by tools that drop unrecognized extra fields, or truncated/malformed downloads of large (>4GB) archives.

Related errors

AI-assisted analysis of can1357/oh-my-pi@9690622007 (2026-08-31). Data as JSON: /api/errors/0c9150c9dc708c08. Report an issue: GitHub.