{"record":{"id":"c4f3c8fe3bb9920e","repo":"vercel/next.js","slug":"failed-to-revalidate-urlpath-err-message","errorCode":null,"errorMessage":"Failed to revalidate ${urlPath}: ${err.message}","messagePattern":"Failed to revalidate (.+?): (.+?)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/next/src/server/api-utils/node/api-resolver.ts","lineNumber":325,"sourceCode":"      // a non-200 status code can be returned from a successful revalidate\n      // e.g. notFound: true returns 404 status code but is successful\n      const cacheHeader =\n        res.headers.get('x-vercel-cache') || res.headers.get('x-nextjs-cache')\n\n      if (\n        cacheHeader?.toUpperCase() !== 'REVALIDATED' &&\n        res.status !== 200 &&\n        !(res.status === 404 && opts.unstable_onlyGenerated)\n      ) {\n        throw new Error(`Invalid response ${res.status}`)\n      }\n    } else {\n      throw new Error(\n        `Invariant: missing internal router-server-methods this is an internal bug`\n      )\n    }\n  } catch (err: unknown) {\n    throw new Error(\n      `Failed to revalidate ${urlPath}: ${isError(err) ? err.message : err}`\n    )\n  }\n}\n\nexport async function apiResolver(\n  req: IncomingMessage,\n  res: ServerResponse,\n  query: any,\n  resolverModule: any,\n  apiContext: ApiContext,\n  propagateError: boolean,\n  dev?: boolean,\n  page?: string,\n  onError?: InstrumentationOnRequestError\n): Promise<void> {\n  const apiReq = req as NextApiRequest\n  const apiRes = res as NextApiResponse","sourceCodeStart":307,"sourceCodeEnd":343,"githubUrl":"https://github.com/vercel/next.js/blob/0ae8c72462952df163f1b1e0726641bc5b40dc93/packages/next/src/server/api-utils/node/api-resolver.ts#L307-L343","documentation":"Thrown by revalidate() as a catch-all wrapper around any error that occurs during the internal revalidation call (network fetch failure, the 'Invalid response' error above, or the missing-router-server invariant). It prefixes the underlying error message with the urlPath so the failing route is identifiable.","triggerScenarios":"Any exception inside the try block of revalidate() — internalRevalidate rejects, the HEAD fetch throws, or one of the inner errors (line 317/321) is raised — gets re-wrapped with 'Failed to revalidate <urlPath>: <message>'.","commonSituations":"Downstream cache layer is unavailable; the origin returns an error (surfaced as the inner 'Invalid response' error); a serverless function timeout; misconfigured revalidation endpoint. The original cause is in the appended message.","solutions":["Read the appended ': <message>' to identify the root cause (network, invalid response, invariant).","Address the underlying error first (e.g. fix the origin status, restore the cache service).","Add retry logic in your revalidation caller for transient failures.","Verify the urlPath is valid and the deployment's revalidation infrastructure is healthy."],"exampleFix":"// before\nawait res.revalidate(path) // may throw 'Failed to revalidate ...'\n// after - caller-side retry\ntry {\n  await res.revalidate(path)\n} catch (err) {\n  console.error('revalidate failed, will retry', err.message)\n  await delay(500)\n  await res.revalidate(path)\n}","handlingStrategy":"retry","validationCode":"function isRevalidateError(err: unknown): boolean {\n  return err instanceof Error && err.message.startsWith('Failed to revalidate')\n}","typeGuard":null,"tryCatchPattern":"async function revalidateWithRetry(res: any, path: string, attempts = 3) {\n  for (let i = 0; i < attempts; i++) {\n    try { await res.revalidate(path); return }\n    catch (err) {\n      if (i === attempts - 1) throw err\n      await new Promise(r => setTimeout(r, 500 * (i + 1)))\n    }\n  }\n}","preventionTips":["Inspect the appended ': <message>' to fix the root cause.","Add retry with backoff for transient revalidation failures.","Monitor revalidation success rates and alert on spikes."],"tags":["api-routes","revalidation","cache","runtime","error-handling"],"analyzedSha":"0ae8c72462952df163f1b1e0726641bc5b40dc93","analyzedAt":"2026-08-06T19:44:29.143Z","schemaVersion":2},"datasetVersion":"2026-08-07T02:17:10.218Z"}