vercel/next.js · error · Error

Failed to revalidate ${urlPath}: ${err.message}

Error message

Failed to revalidate ${urlPath}: ${err.message}

What it means

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.

Source

Thrown at packages/next/src/server/api-utils/node/api-resolver.ts:325

      // a non-200 status code can be returned from a successful revalidate
      // e.g. notFound: true returns 404 status code but is successful
      const cacheHeader =
        res.headers.get('x-vercel-cache') || res.headers.get('x-nextjs-cache')

      if (
        cacheHeader?.toUpperCase() !== 'REVALIDATED' &&
        res.status !== 200 &&
        !(res.status === 404 && opts.unstable_onlyGenerated)
      ) {
        throw new Error(`Invalid response ${res.status}`)
      }
    } else {
      throw new Error(
        `Invariant: missing internal router-server-methods this is an internal bug`
      )
    }
  } catch (err: unknown) {
    throw new Error(
      `Failed to revalidate ${urlPath}: ${isError(err) ? err.message : err}`
    )
  }
}

export async function apiResolver(
  req: IncomingMessage,
  res: ServerResponse,
  query: any,
  resolverModule: any,
  apiContext: ApiContext,
  propagateError: boolean,
  dev?: boolean,
  page?: string,
  onError?: InstrumentationOnRequestError
): Promise<void> {
  const apiReq = req as NextApiRequest
  const apiRes = res as NextApiResponse

View on GitHub (pinned to 0ae8c72462)

Solutions

1. Read the appended ': <message>' to identify the root cause (network, invalid response, invariant).
2. Address the underlying error first (e.g. fix the origin status, restore the cache service).
3. Add retry logic in your revalidation caller for transient failures.
4. Verify the urlPath is valid and the deployment's revalidation infrastructure is healthy.

Example fix

// before
await res.revalidate(path) // may throw 'Failed to revalidate ...'
// after - caller-side retry
try {
  await res.revalidate(path)
} catch (err) {
  console.error('revalidate failed, will retry', err.message)
  await delay(500)
  await res.revalidate(path)
}

function isRevalidateError(err: unknown): boolean {
  return err instanceof Error && err.message.startsWith('Failed to revalidate')
}

async function revalidateWithRetry(res: any, path: string, attempts = 3) {
  for (let i = 0; i < attempts; i++) {
    try { await res.revalidate(path); return }
    catch (err) {
      if (i === attempts - 1) throw err
      await new Promise(r => setTimeout(r, 500 * (i + 1)))
    }
  }
}

When it happens

Trigger: 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>'.

Common situations: 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.

Related errors

• Invalid urlPath provided to revalidate(), must be a path e.g
• Invalid response ${res.status}
• Invalid redirect arguments. Please use a single argument URL
• Preview data is limited to 2KB currently, reduce how much da
• `${name}` is only available in a Server Component.

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