Extraction produced unexpected layout — index.html not found

Error message

Extraction produced unexpected layout — index.html not found in extracted dir

What it means

After tar exits successfully, downloadWebDist validates that the extraction produced the expected layout by checking for index.html at the root of the temp dir. If it is absent, the archive's internal structure doesn't match what the server expects to serve (the web dist root), so the run is aborted and the temp dir cleaned up. This catches packaging drift where files end up nested one level deeper.

Source

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

    // 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) {
    cleanupAndThrow(
      tmpDir,
      `Failed to move extracted web UI from ${tmpDir} to ${targetDir}: ${toError(err).message}`
    );
  }
  // Closes the last phase: staged-archive removal, layout check, and the rename
  // of a freshly written tree — all after-tar filesystem work.
  log.info(

View on GitHub (pinned to 0773b97458)

Solutions

Inspect the tarball (`tar -tzf archon-web.tar.gz | head`) — if files sit under a wrapper dir, the release packaging changed; upgrade the CLI or report the release.
Use the matching release: ensure the downloaded web artifact version corresponds to the installed CLI version.
If you must unblock, repackage the tarball so index.html is at the archive root and serve from a pinned local artifact if supported.
Check for an extraction-side skip (permissions, excluded files) in the tar details before blaming packaging.

Defensive patterns

Strategy: validation

Validate before calling

import { execSync } from 'node:child_process';
const listing = execSync('tar -tzf archon-web.tar.gz', { encoding: 'utf8' });
if (!listing.split('\n').some((n) => n === 'index.html' || n === './index.html')) {
  throw new Error('Archive layout check failed: index.html is not at tarball root; artifact packaging drifted');
}

Try / catch

try {
  await serveCommand();
} catch (err) {
  if (err instanceof Error && err.message.includes('index.html not found in extracted dir')) {
    // inspect `tar -tzf` output; if files are nested under a wrapper dir,
    // upgrade/pin the CLI to match the release packaging or report it upstream.
  } else throw err;
}

Prevention

Match CLI and web artifact versions — layout is a contract between them.
Sanity-check release artifacts (`tar -tzf | head`) after any packaging pipeline change.
Don't substitute locally built tarballs with a different directory layout.
Add a CI step that extracts the artifact and asserts index.html at root before publishing.

When it happens

Trigger: serveCommand -> downloadWebDist -> tar succeeds but `${tmpDir}/index.html` does not exist: the archive wraps files in a top-level directory (e.g. dist/), the release packaged the wrong directory, or extraction silently skipped the file.

Common situations: Release pipeline change that starts emitting a versioned top-level folder inside the tarball; hand-built or locally substituted tarball with a different layout; mismatched web artifact version fetched for an older CLI expecting the flat layout.

Related errors

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