{"record":{"id":"0c3fe9d9f22a4e24","repo":"withastro/astro","slug":"astro-cache-background-revalidation-failed-for","errorCode":null,"errorMessage":"[astro:cache] Background revalidation failed for ${requestUrl.pathname}${requestUrl.search}: ${String(error)}","messagePattern":"\\[astro:cache\\] Background revalidation failed for (.+?)(.+?): (.+?)","errorType":"console","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"packages/astro/src/core/cache/memory-provider.ts","lineNumber":470,"sourceCode":"\t\t\t\t\t\t\t\t\t\treturn;\n\t\t\t\t\t\t\t\t\t}\n\t\t\t\t\t\t\t\t\tconst newTags = parseCacheTags(freshResponse.headers.get('Cache-Tag'));\n\t\t\t\t\t\t\t\t\tconst newEntry = await serializeResponse(\n\t\t\t\t\t\t\t\t\t\tfreshResponse,\n\t\t\t\t\t\t\t\t\t\tcontext.request,\n\t\t\t\t\t\t\t\t\t\tnewMaxAge,\n\t\t\t\t\t\t\t\t\t\tnewSwr,\n\t\t\t\t\t\t\t\t\t\tnewTags,\n\t\t\t\t\t\t\t\t\t);\n\t\t\t\t\t\t\t\t\t// Update Vary map if the response changed its Vary headers\n\t\t\t\t\t\t\t\t\tif (newEntry.vary) {\n\t\t\t\t\t\t\t\t\t\tvaryMap.set(primaryKey, newEntry.vary);\n\t\t\t\t\t\t\t\t\t}\n\t\t\t\t\t\t\t\t\tcache.set(key, newEntry);\n\t\t\t\t\t\t\t\t}\n\t\t\t\t\t\t\t})\n\t\t\t\t\t\t\t.catch((error) => {\n\t\t\t\t\t\t\t\tconsole.warn(\n\t\t\t\t\t\t\t\t\t`[astro:cache] Background revalidation failed for ${requestUrl.pathname}${requestUrl.search}: ${String(\n\t\t\t\t\t\t\t\t\t\terror,\n\t\t\t\t\t\t\t\t\t)}`,\n\t\t\t\t\t\t\t\t);\n\t\t\t\t\t\t\t});\n\n\t\t\t\t\t\tconst response = createResponseFromCacheEntry(cached);\n\t\t\t\t\t\tresponse.headers.set('X-Astro-Cache', 'STALE');\n\t\t\t\t\t\treturn response;\n\t\t\t\t\t}\n\t\t\t\t}\n\n\t\t\t\t// Past SWR window or Vary mismatch — expired, treat as miss\n\t\t\t}\n\n\t\t\t// Cache miss — render fresh\n\t\t\tconst response = await next();\n","sourceCodeStart":452,"sourceCodeEnd":488,"githubUrl":"https://github.com/withastro/astro/blob/3578d45d34226d63cff3d261c971c221de6794d2/packages/astro/src/core/cache/memory-provider.ts#L452-L488","documentation":"Astro's experimental in-memory cache serves entries past max-age while `staleWhileRevalidate` permits it, returning the STALE copy immediately (X-Astro-Cache: STALE) and refreshing in the background. If that background revalidation fetch to your origin rejects — network error, DNS failure, upstream 5xx thrown by the cached function — this warning prints the URL and error. The current visitor already got the stale copy, so nothing user-facing failed; the next request simply retries revalidation.","triggerScenarios":"Using `cache(key, fetcher, { expiresIn, staleWhileRevalidate })` where the fetcher rejects after the entry has gone stale — upstream unreachable, DNS failure, or the handler throws while refreshing.","commonSituations":"Dev machine briefly offline; upstream API having an incident while the cache keeps serving stale data; aggressive revalidation during cold starts; CI environments without network egress.","solutions":["Verify the origin URL from the message with curl — the warning mirrors upstream availability","Treat it as transient noise during upstream incidents: stale content keeps serving, which is the feature working","Harden the cached fetcher (timeout + one retry) so transient origin blips don't log at all","Revisit expiresIn/staleWhileRevalidate windows if your origin is too flaky to revalidate reliably"],"exampleFix":null,"handlingStrategy":"retry","validationCode":null,"typeGuard":null,"tryCatchPattern":"// Endpoints: degrade gracefully when even the cache layer is unhealthy\nexport const GET = async ({ cache }) => {\n  try {\n    return await cache('products', () => fetch(PRODUCTS_API), {\n      expiresIn: 60,\n      staleWhileRevalidate: 3600,\n    });\n  } catch {\n    return new Response('upstream unavailable', { status: 503 });\n  }\n};","preventionTips":["Give cached fetchers a timeout and one retry so transient origin blips never reach the warning","Size staleWhileRevalidate windows to your origin's real reliability","Monitor the origin separately — this warning is a symptom, not the disease"],"tags":["cache","stale-while-revalidate","network","experimental"],"backgroundTag":"stale-while-revalidate-error","analyzedSha":"3578d45d34226d63cff3d261c971c221de6794d2","analyzedAt":"2026-08-18T18:48:03.901Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}