{"record":{"id":"a9417e32a4af6229","repo":"vercel/next.js","slug":"proxy-request-failed-resp-status","errorCode":null,"errorMessage":"Proxy request failed: ${resp.status}","messagePattern":"Proxy request failed: (.+?)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/next/src/experimental/testmode/fetch.ts","lineNumber":115,"sourceCode":"\n  const resp = await originalFetch(`http://localhost:${proxyPort}`, {\n    method: 'POST',\n    body: JSON.stringify(proxyRequest),\n    // The header lets the ClientRequest interception in `httpget.ts` identify\n    // this request as part of the test proxy protocol. @mswjs/interceptors\n    // intercepts at the TCP level, so this request would otherwise be\n    // intercepted again when it's sent from within an interception listener,\n    // recursing indefinitely.\n    headers: {\n      'next-test-internal': '1',\n    },\n    next: {\n      // @ts-ignore\n      internal: true,\n    },\n  })\n  if (!resp.ok) {\n    throw new Error(`Proxy request failed: ${resp.status}`)\n  }\n\n  const proxyResponse = (await resp.json()) as ProxyResponse\n  const { api } = proxyResponse\n  switch (api) {\n    case 'continue':\n      return originalFetch(request)\n    case 'abort':\n    case 'unhandled':\n      throw new Error(\n        `Proxy request aborted [${request.method} ${request.url}]`\n      )\n    case 'fetch':\n      return buildResponse(proxyResponse)\n    default:\n      return api satisfies never\n  }\n}","sourceCodeStart":97,"sourceCodeEnd":133,"githubUrl":"https://github.com/vercel/next.js/blob/0ae8c72462952df163f1b1e0726641bc5b40dc93/packages/next/src/experimental/testmode/fetch.ts#L97-L133","documentation":"Thrown by the experimental testmode fetch interceptor when the local proxy server (running on proxyPort during `next dev`/test) returns a non-2xx status for the proxied fetch request. The testmode routes every fetch through a proxy so tests can mock responses; a failing proxy response means the test harness itself is misbehaving or rejected the request envelope.","triggerScenarios":"Triggered inside Next.js's experimental.testmode when a server component calls fetch(), the interceptor forwards it to the test proxy at localhost:proxyPort, and resp.ok is false. The proxy server crashed, returned 500, or the request body/headers were malformed.","commonSituations":"The test proxy process died or was not started; a mock handler in the test threw an exception causing a 500; mismatched Next.js versions between the test harness and the framework; or a port conflict on the proxy port. Also seen when testmode is partially configured (configuration set but no httpMockHandler registered).","solutions":["Verify the test proxy is running and listening on proxyPort; restart the dev/test server if it crashed.","Inspect the proxy server logs for the failing request and fix the underlying handler that returned the error status.","Confirm experimental.testmode is fully configured with a valid testApiHandler/httpMockHandler in next.config.js.","Bypass the proxy for unrelated fetches by marking them with `next: { internal: true }` if they should passthrough."],"exampleFix":"// before — mock handler throws, proxy returns 500\nasync function handler(req) {\n  return Response.json(JSON.parse(badJson)) // throws\n}\n// after — guard the handler\nasync function handler(req) {\n  try {\n    return Response.json(JSON.parse(badJson))\n  } catch {\n    return new Response('bad input', { status: 400 })\n  }\n}","handlingStrategy":"try-catch","validationCode":"// Before relying on the proxy, health-check it\nasync function proxyAlive(port: number): Promise<boolean> {\n  try {\n    const r = await fetch(`http://localhost:${port}`, { method: 'HEAD' })\n    return r.ok || r.status === 405 // some servers reject HEAD\n  } catch { return false }\n}","typeGuard":null,"tryCatchPattern":"try {\n  return await handleFetch(originalFetch, request)\n} catch (e) {\n  if (/Proxy request failed/.test(e.message)) {\n    // surface the failing request, optionally fall back to originalFetch(request)\n    console.error('testmode proxy failed for', request.url)\n  }\n  throw e\n}","preventionTips":["Ensure the testmode proxy is started before tests run.","Make mock handlers total — never throw; return explicit error responses instead.","Pin Next.js version across test harness and framework.","Log every proxied request during local test runs to catch 500s early."],"tags":["testmode","experimental","network","fetch","testing"],"analyzedSha":"0ae8c72462952df163f1b1e0726641bc5b40dc93","analyzedAt":"2026-08-06T19:44:29.143Z","schemaVersion":2},"datasetVersion":"2026-08-07T02:17:10.218Z"}