Missing ${NEXT_BIN}. Build Next.js first (pnpm --filter=next

Error message

Missing ${NEXT_BIN}. Build Next.js first (pnpm --filter=next build).

What it means

Thrown at the start of client-trace main() when fs.access(NEXT_BIN) fails, meaning the compiled Next.js CLI binary (packages/next/dist/bin/next) does not exist. The tracer needs that binary to build and/or start the fixture app, so a missing build is a hard prerequisite. The message gives the exact build command.

Source

Thrown at bench/render-pipeline/client-trace.ts:603

    console.log(
      `    off thread  parse-background=${m.parseBackgroundMs.toFixed(1)}ms`
    )
    console.log(
      `    blocking    longTasks(pre-hydration)=${m.longTasksToHydrated ?? 'n/a'} tbt=${m.blockingTimeToHydratedMs === null ? 'n/a' : `${m.blockingTimeToHydratedMs.toFixed(1)}ms`}`
    )
    console.log(
      `    js          ${formatKb(m.jsTransferBytes)} transferred / ${formatKb(m.jsParsedBytes)} parsed (${m.jsFileCount} files)`
    )
  }
}

async function main() {
  const options = parseCli()

  try {
    await access(NEXT_BIN)
  } catch {
    throw new Error(
      `Missing ${NEXT_BIN}. Build Next.js first (pnpm --filter=next build).`
    )
  }

  await mkdir(options.artifactDir, { recursive: true })

  if (options.build) {
    const generator = resolve(
      options.appDir,
      'scripts/generate-client-graph.mjs'
    )
    if (existsSync(generator)) {
      await runCommand('node', [generator], options.appDir)
    }
    console.log('[client-trace] building app fixture...')
    await runCommand('node', [NEXT_BIN, 'build'], options.appDir)
  }

View on GitHub (pinned to 0ae8c72462)

Solutions

Run pnpm --filter=next build to produce the binary.
If on a fresh checkout or after bootstrap, run pnpm build-all.
Verify packages/next/dist/bin/next exists after building.

Example fix

# before
ls packages/next/dist/bin/next  # missing

# after
pnpm --filter=next build
ls packages/next/dist/bin/next  # exists

Defensive patterns

Strategy: validation

Validate before calling

import { access, constants } from 'node:fs/promises'
async function ensureBuilt() {
  try { await access(NEXT_BIN, constants.X_OK) }
  catch { throw new Error(`Missing ${NEXT_BIN}. Run pnpm --filter=next build first.`) }
}

Type guard

null

Try / catch

null

Prevention

Run pnpm --filter=next build (or pnpm build-all) after fresh checkout or branch switch.
Never delete packages/next/dist without rebuilding.
Add a build check at the start of any benchmark script.

When it happens

Trigger: Fresh checkout without building; deleted dist/; switched branches that removed the build; the path constant NEXT_BIN points somewhere unexpected.

Common situations: First run in a new clone; ran pnpm clean or rm -rf packages/next/dist; partial build that did not emit the bin.

Related errors

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