coleam00/Archon · error

tar extraction failed (exit ${exitCode}): ${details}

Error message

tar extraction failed (exit ${exitCode}): ${details}

What it means

downloadWebDist extracts the verified tarball by shelling out to the system `tar` binary with a timeout; cleanupAndThrow removes the temp dir and raises this error when tar exits non-zero. It includes the exit code and captured stderr/stdout details to explain why extraction failed. A kill by signal (e.g. timeout) is reported separately with a distinct message.

Source

Thrown at packages/cli/src/commands/serve.ts:253

        signalCode: proc.signalCode,
        durationMs: Math.round(extractionEndedAt - spawnedAt),
      },
      'web_dist.extract_exited'
    );
    const details = stderrText.trim();
    // A signal means `tar` never finished. `proc.killed` cannot say so — it is
    // true after any exit — and a signal can also come from outside this process,
    // so report how long it actually ran instead of asserting the bound fired.
    if (proc.signalCode !== null) {
      const elapsedMs = Math.round(extractionEndedAt - extractionStartedAt);
      cleanupAndThrow(
        tmpDir,
        `tar extraction was killed by ${proc.signalCode} after ${elapsedMs}ms without finishing ` +
          `(limit ${EXTRACTION_TIMEOUT_MS}ms): ${details}`
      );
    }
    if (exitCode !== 0) {
      cleanupAndThrow(tmpDir, `tar extraction failed (exit ${exitCode}): ${details}`);
    }
  } finally {
    rmSync(tarballPath, { force: true });
  }

  // Verify extraction produced expected layout
  if (!existsSync(`${tmpDir}/index.html`)) {
    cleanupAndThrow(
      tmpDir,
      'Extraction produced unexpected layout — index.html not found in extracted dir'
    );
  }

  // Atomic move into place
  mkdirSync(dirname(targetDir), { recursive: true });
  try {
    renameSync(tmpDir, targetDir);
  } catch (err) {

View on GitHub (pinned to 0773b97458)

Solutions

  1. Read `details` in the message — it contains tar's stderr; fix the underlying cause it names (permissions, disk space, bad flag).
  2. Check the installed tar (`tar --version`) and ensure a modern GNU tar or compatible bsdtar is on PATH.
  3. Free disk space and confirm TMPDIR points to a writable, non-noexec location.
  4. Re-download the tarball if details suggest a corrupt archive, then retry serve.
Defensive patterns

Strategy: validation

Validate before calling

import { execSync } from 'node:child_process';
const version = execSync('tar --version', { encoding: 'utf8' });
if (!/GNU tar|bsdtar/.test(version)) {
  throw new Error(`Unsupported tar on PATH: ${version.split('\n')[0]}; install GNU tar before serving`);
}
// and check tmp writability + free space
import { statfsSync } from 'node:fs';
const { bavail, bsize } = statfsSync(tmpParent);
if (bavail * bsize < 512 * 1024 * 1024) throw new Error('Less than 512MB free in TMPDIR');

Try / catch

try {
  await serveCommand();
} catch (err) {
  if (err instanceof Error && err.message.startsWith('tar extraction failed')) {
    // read the captured tar stderr after 'exit N:'; fix disk/permissions/flag
    // issue it names, then re-run serve.
  } else throw err;
}

Prevention

When it happens

Trigger: serveCommand -> downloadWebDist spawns `tar` on the downloaded archive; the process finishes with exitCode !== 0: corrupted archive despite a valid checksum path, unsupported tar flags on the platform (e.g. BSD vs GNU tar), disk full, permission errors in temp dir, or archive containing paths tar refuses to write.

Common situations: Non-GNU tar (macOS bsdtar, busybox tar) rejecting a GNU-specific flag; TMPDIR on a full or noexec filesystem; tarball produced by a newer packaging script with options the installed tar doesn't support; antivirus locking files during extraction.

Related errors

AI-assisted analysis of coleam00/Archon@0773b97458 (2026-09-01). Data as JSON: /api/errors/118464dfcbbc3dc4. Report an issue: GitHub.