{"record":{"id":"19e99de7bda55d5a","repo":"vercel/next.js","slug":"npm-install-next-tgz-failed-exit-exitcode","errorCode":null,"errorMessage":"npm install ./next.tgz failed (exit ${exitCode}):\n${stderr}","messagePattern":"npm install \\./next\\.tgz failed \\(exit (.+?)\\):\n(.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"evals/lib/setup.ts","lineNumber":29,"sourceCode":" */\nexport async function installNextJs(sandbox: Sandbox): Promise<void> {\n  const tarball = process.env.NEXT_EVAL_TARBALL\n  if (!tarball) {\n    throw new Error(\n      'NEXT_EVAL_TARBALL not set. Run evals via `pnpm eval` from the repo root.'\n    )\n  }\n  await sandbox.writeFiles({\n    // @ts-expect-error — upstream types writeFiles as Record<string, string>\n    // but the runtime accepts Buffer. Tarballs are binary; can't send as string.\n    'next.tgz': readFileSync(tarball),\n  })\n  const { exitCode, stderr } = await sandbox.runCommand('npm', [\n    'install',\n    './next.tgz',\n  ])\n  if (exitCode !== 0) {\n    throw new Error(\n      `npm install ./next.tgz failed (exit ${exitCode}):\\n${stderr}`\n    )\n  }\n}\n\n/**\n * Write AGENTS.md (and aliases) to the sandbox root, directing agents to read\n * bundled docs from node_modules/next/dist/docs/.\n */\nexport async function writeAgentsMd(sandbox: Sandbox): Promise<void> {\n  const body = `<!-- BEGIN:nextjs-agent-rules -->\n\n# Next.js: ALWAYS read docs before coding\n\nBefore 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.\n\n<!-- END:nextjs-agent-rules -->\n`","sourceCodeStart":11,"sourceCodeEnd":47,"githubUrl":"https://github.com/vercel/next.js/blob/0ae8c72462952df163f1b1e0726641bc5b40dc93/evals/lib/setup.ts#L11-L47","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"# inspect the failed install\ntar -tzf next.tgz | head   # confirm valid archive\n# rebuild and rerun\npnpm --filter=next build\npnpm eval","handlingStrategy":"try-catch","validationCode":"// Validate the tarball before passing it to installNextJs.\nimport { existsSync, statSync } from 'node:fs'\nfunction assertTarball(p: string) {\n  if (!existsSync(p) || statSync(p).size < 1024) {\n    throw new Error(`Tarball missing or too small: ${p}`)\n  }\n}","typeGuard":null,"tryCatchPattern":"const { exitCode, stderr } = await sandbox.runCommand('npm', ['install', './next.tgz'])\nif (exitCode !== 0) {\n  // surface stderr verbatim, classify common causes\n  if (/EAI_AGAIN|ENOTFOUND/.test(stderr)) console.error('Network/registry issue in sandbox')\n  throw new Error(`npm install ./next.tgz failed (exit ${exitCode}):\\n${stderr}`)\n}","preventionTips":["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."],"tags":["evals","tooling","npm","tarball","ci","environment"],"analyzedSha":"0ae8c72462952df163f1b1e0726641bc5b40dc93","analyzedAt":"2026-08-06T19:44:29.143Z","schemaVersion":2},"datasetVersion":"2026-08-07T02:17:10.218Z"}