vercel-labs/skills · error · Error

Invalid zip64 locator

Error message

Invalid zip64 locator

What it means

When zip64 sentinels are present, the parser reads a 20-byte zip64 end-of-central-directory locator immediately before the normal end record. If the signature at the start of that locator is not the expected ZIP64_END_OF_CENTRAL_DIRECTORY_LOCATOR magic, the file is not a valid zip64 archive and this error is thrown. It typically means the file is corrupt, truncated, or the sentinel values were a coincidence of corruption.

Source

Thrown at src/archive.ts:102

    totalEntries === 0xffff ||
    size === 0xffffffff ||
    offset === 0xffffffff;

  if (!usesZip64) {
    if (diskNumber !== 0 || centralDirectoryDisk !== 0 || entriesOnDisk !== totalEntries) {
      throw new Error('Multi-disk zip archives are not supported');
    }
    return { entries: totalEntries, offset, size, trailerOffset: endOffset };
  }

  if (diskNumber !== 0 || centralDirectoryDisk !== 0) {
    throw new Error('Multi-disk zip archives are not supported');
  }

  const locatorOffset = endOffset - 20;
  ensureRange(buffer, locatorOffset, 20, 'zip64 locator');
  if (buffer.readUInt32LE(locatorOffset) !== ZIP64_END_OF_CENTRAL_DIRECTORY_LOCATOR) {
    throw new Error('Invalid zip64 locator');
  }
  if (
    buffer.readUInt32LE(locatorOffset + 4) !== 0 ||
    buffer.readUInt32LE(locatorOffset + 16) !== 1
  ) {
    throw new Error('Multi-disk zip archives are not supported');
  }

  const zip64EndOffset = readUInt64AsNumber(buffer, locatorOffset + 8, 'zip64 end offset');
  ensureRange(buffer, zip64EndOffset, 56, 'zip64 end of central directory');
  if (buffer.readUInt32LE(zip64EndOffset) !== ZIP64_END_OF_CENTRAL_DIRECTORY) {
    throw new Error('Invalid zip64 end of central directory');
  }

  const recordSize = readUInt64AsNumber(buffer, zip64EndOffset + 4, 'zip64 end size');
  if (recordSize < 44) {
    throw new Error('Invalid zip64 end of central directory');
  }

View on GitHub (pinned to 435076e789)

Solutions

  1. Verify with `unzip -t file.zip`; if it also fails, re-obtain the archive from the source.
  2. Rebuild the archive: `zip -FF file.zip --out fixed.zip` can reconstruct central directories and locators.
  3. If you create the archives, upgrade your zip-writing library (e.g. older yauzl/jszip/ adm-zip versions had zip64 bugs) to one with correct zip64 locator emission.

Example fix

# before
readZipArchive(buffer); // throws 'Invalid zip64 locator'

# after
# repair the central directory / locator chain
zip -FF broken.zip --out fixed.zip
readZipArchive(await fs.promises.readFile('fixed.zip'));
Defensive patterns

Strategy: try-catch

Validate before calling

function hasValidZip64Locator(buffer: Buffer, eocd: number): boolean {
  const loc = eocd - 20;
  if (loc < 0) return false;
  return buffer.readUInt32LE(loc) === 0x07064b50;
}

Type guard

null

Try / catch

try {
  const zip = readZipArchive(buffer);
} catch (e) {
  if ((e as Error).message === 'Invalid zip64 locator') {
    // attempt repair via zip -FF, or reject
  }
  throw e;
}

Prevention

When it happens

Trigger: An end record with 0xffffffff offset/size sentinels but a missing, overwritten, or corrupt zip64 locator; appending data to a zip without rewriting trailers; fuzzed buffers where random bytes match the EOCD signature but the preceding 20 bytes are not a locator.

Common situations: Self-extracting executables or archives with prepended/appended data that break locator placement; partially overwritten files (disk corruption, concurrent writes); files processed by tools that write zip64 sentinels incorrectly.

Related errors

AI-assisted analysis of vercel-labs/skills@435076e789 (2026-08-28). Data as JSON: /api/errors/dcdb627c567bf3fa. Report an issue: GitHub.