What causes "npm install ./next.tgz failed (exit ${exitCode}): ${stderr}" in vercel/next.js?

Inspect the inlined stderr — it usually names the exact failing package or network error.

npm install ./next.tgz failed (exit ${exitCode}): ${stderr}

Error message

npm install ./next.tgz failed (exit ${exitCode}):
${stderr}

What it means

Thrown by the eval setup after it copied the local `next.tgz` into the sandbox and ran `npm install ./next.tgz`. A non-zero exit code from npm (with the captured stderr inlined) means the tarball could not be installed in the sandbox — common causes are a corrupt/incomplete tarball, missing peer deps, or the sandbox environment lacking network/registry access for transitive deps.

Source

Thrown at evals/lib/setup.ts:29

 */
export async function installNextJs(sandbox: Sandbox): Promise<void> {
  const tarball = process.env.NEXT_EVAL_TARBALL
  if (!tarball) {
    throw new Error(
      'NEXT_EVAL_TARBALL not set. Run evals via `pnpm eval` from the repo root.'
    )
  }
  await sandbox.writeFiles({
    // @ts-expect-error — upstream types writeFiles as Record<string, string>
    // but the runtime accepts Buffer. Tarballs are binary; can't send as string.
    'next.tgz': readFileSync(tarball),
  })
  const { exitCode, stderr } = await sandbox.runCommand('npm', [
    'install',
    './next.tgz',
  ])
  if (exitCode !== 0) {
    throw new Error(
      `npm install ./next.tgz failed (exit ${exitCode}):\n${stderr}`
    )
  }
}

/**
 * Write AGENTS.md (and aliases) to the sandbox root, directing agents to read
 * bundled docs from node_modules/next/dist/docs/.
 */
export async function writeAgentsMd(sandbox: Sandbox): Promise<void> {
  const body = `<!-- BEGIN:nextjs-agent-rules -->

# Next.js: ALWAYS read docs before coding

Before any Next.js work, find and read the relevant doc in \`node_modules/next/dist/docs/\`. Your training data is outdated — the docs are the source of truth.

<!-- END:nextjs-agent-rules -->
`

View on GitHub (pinned to 0ae8c72462)

Solutions

Inspect the inlined stderr — it usually names the exact failing package or network error.
Rebuild the next package cleanly (`pnpm --filter=next build`) and re-run `pnpm eval` to regenerate the tarball.
If stderr shows registry/network errors, ensure the sandbox can reach the npm registry (or pre-populate the cache).
Verify the tarball is a valid gzip (`tar -tzf next.tgz | head`) before retrying.

Example fix

# inspect the failed install
tar -tzf next.tgz | head   # confirm valid archive
# rebuild and rerun
pnpm --filter=next build
pnpm eval

Defensive patterns

Strategy: try-catch

Validate before calling

// Validate the tarball before passing it to installNextJs.
import { existsSync, statSync } from 'node:fs'
function assertTarball(p: string) {
  if (!existsSync(p) || statSync(p).size < 1024) {
    throw new Error(`Tarball missing or too small: ${p}`)
  }
}

Try / catch

const { exitCode, stderr } = await sandbox.runCommand('npm', ['install', './next.tgz'])
if (exitCode !== 0) {
  // surface stderr verbatim, classify common causes
  if (/EAI_AGAIN|ENOTFOUND/.test(stderr)) console.error('Network/registry issue in sandbox')
  throw new Error(`npm install ./next.tgz failed (exit ${exitCode}):\n${stderr}`)
}

Prevention

Build the next package fully before packing the tarball.
Ensure sandbox has network access for transitive deps (or pre-cache).
Capture stderr to diagnose the failing package.

When it happens

Trigger: The locally-built tarball is malformed (e.g. build was interrupted, or `next pack` ran against a stale dist), the tarball's package.json references deps the sandbox cannot resolve, or `npm install` hit a registry/network error captured in stderr.

Common situations: Running evals against a half-built next package; CI sandbox with restricted egress; version mismatch where the tarball's peerDependencies don't match the sandbox template; disk space issues in the sandbox.

Related errors

AI-assisted analysis of vercel/next.js@0ae8c72462 (2026-08-06). Data as JSON: /api/errors/19e99de7bda55d5a. Report an issue: GitHub.