_runheed
Sign in

Next.js error tracking your coding agent can read

In production, Next.js hides server component errors behind a digest ("The specific message is omitted in production builds"). Runheed records the real error on the server through the onRequestError hook in instrumentation.ts, with the route and request, and your coding agent reads it over MCP.

Set it up

  1. 1.Install the SDK.

    terminalbash
    npm install https://runheed.com/dl/runheed-0.1.0.tgz

  2. 2.Create instrumentation.ts in the project root (or src/). register() runs once per server start; onRequestError runs for every uncaught server error in the Node.js runtime.

    instrumentation.tstypescript
    export async function register() {
  if (process.env.NEXT_RUNTIME === 'nodejs') {
    const runheed = (await import('runheed')).default;
    runheed.init({ dsn: process.env.RUNHEED_DSN!, environment: process.env.NODE_ENV });
  }
}

export async function onRequestError(
  err: unknown,
  request: { path: string; method: string },
  context: { routePath: string; routeType: string },
) {
  if (process.env.NEXT_RUNTIME !== 'nodejs') return;
  const runheed = (await import('runheed')).default;
  runheed.captureException(err as Error, {
    path: request.path,
    method: request.method,
    routePath: context.routePath,
    routeType: context.routeType,
  });
}

  3. 3.Set RUNHEED_DSN in your deploy platform's environment, then connect your agent (one command for Claude Code).

    terminalbash
    claude mcp add runheed -e RUNHEED_API_KEY=al_... -- npx -y https://runheed.com/dl/runheed-mcp-0.1.0.tgz

The npm and PyPI releases are not out yet, so these commands install the same package files straight from runheed.com. Nothing else changes when the registry versions ship.

What it catches

  • Server component and route handler errors, including the real message behind the production digest
  • Server action failures
  • Errors in API routes and proxy code running on the Node.js runtime

What it does not do

  • Edge runtime routes are skipped in this setup (the SDK uses Node.js APIs)
  • Browser-only errors are not captured automatically; there is no browser SDK yet

Then ask your agent

> what broke in production since the last deploy? fix the top one and resolve it with the commit hash

Common Next.js errors

Plans from $29/moOther agents and editors30-day money-back guarantee