Yeachan-Heo/oh-my-codex · error · Error

archive_inspection_failed

archive_inspection_failed

Error message

[native-assets] archive_inspection_failed: invalid entry size: ${rawName}

What it means

While listing archive entries, the inspector parses each entry's size and rejects values that are not safe non-negative integers (NaN, fractional, negative, or beyond Number.MAX_SAFE_INTEGER) by throwing archive_inspection_failed with 'invalid entry size'. This almost always indicates a corrupt or maliciously crafted archive whose header metadata is garbage.

Source

Thrown at src/native-assets/archive.ts:39

  /** @deprecated Use normalizedName. */
  path: string;
  type: NativeArchiveEntryType;
  size: number;
}

function archiveError(code: string, detail: string): Error {
  return new Error(`[native-assets] ${code}: ${detail}`);
}

function archiveFormat(archivePath: string): 'tar.xz' | 'tar.gz' | 'zip' {
  if (/\.tar\.xz$/i.test(archivePath)) return 'tar.xz';
  if (/\.tar\.gz$/i.test(archivePath)) return 'tar.gz';
  if (/\.zip$/i.test(archivePath)) return 'zip';
  throw archiveError('archive_format_unsupported', archivePath);
}

function entry(rawName: string, type: NativeArchiveEntryType, size: number): NativeArchiveEntry {
  if (!Number.isSafeInteger(size) || size < 0) throw archiveError('archive_inspection_failed', `invalid entry size: ${rawName}`);
  const normalizedName = normalizeNativeArchivePath(rawName, type);
  return { rawName, normalizedName, path: normalizedName, type, size };
}

async function tarInput(archivePath: string, format: 'tar.xz' | 'tar.gz'): Promise<Readable> {
  try {
    const archive = readFileSync(archivePath);
    return Readable.from(format === 'tar.gz' ? gunzipSync(archive) : await decompress(archive));
  } catch (error) {
    throw archiveError('archive_inspection_failed', error instanceof Error ? error.message : archivePath);
  }
}

async function inspectTar(archivePath: string, format: 'tar.xz' | 'tar.gz'): Promise<NativeArchiveEntry[]> {
  const entries: NativeArchiveEntry[] = [];
  const extractor = tar.extract();
  extractor.on('entry', (header, source, next) => {
    try {

View on GitHub (pinned to 3ad79a8a6f)

Solutions

1. Re-download or regenerate the archive from a trusted source and verify its checksum before inspecting
2. Validate the archive with an external tool (tar -t, unzip -l) to confirm the corruption
3. If accepting user-supplied archives, pre-scan and reject malformed ones before calling the inspector
4. Report upstream if the archive opens fine in other tools (possible parser bug)

// Verify integrity before inspecting
import { createHash } from 'node:crypto';
const actual = createHash('sha256').update(await readFile(archivePath)).digest('hex');
if (actual !== expectedSha256) throw new Error('archive checksum mismatch');

function isArchiveInspectionFailure(e: unknown): e is { code: 'archive_inspection_failed' } {
  return (e as { code?: string })?.code === 'archive_inspection_failed';
}

catch (e) {
  if (isArchiveInspectionFailure(e)) {
    // reject the input; do not retry — the archive bytes are bad
    quarantine(archivePath);
  } else throw e;
}

When it happens

Trigger: inspectTar/inspectZip encountering an entry whose declared size in the tar/zip header fails Number.isSafeInteger(size) || size < 0 — truncated archives, headers overwritten, or adversarial zip-bomb-style metadata.

Common situations: Truncated downloads (interrupted fetch of a release artifact); archives corrupted in transit or by storage; hand-crafted/modified archives; cross-generator archives writing 64-bit sizes that overflow when parsed incorrectly.

Related errors

• Unknown adapt target: ${target}
• native_agent_canonical_invalid
• archive_format_unsupported
• manifest_binary_product_mismatch
• invalid auth slot name: use 1-64 letters, numbers, '.', '_'

AI-assisted analysis of Yeachan-Heo/oh-my-codex@3ad79a8a6f (2026-08-27). Data as JSON: /api/errors/cf28f3d27eaf8d06. Report an issue: GitHub.