{"record":{"id":"63e1c6a7e891219f","repo":"withastro/astro","slug":"cachenotenabled-63e1c6","errorCode":"CacheNotEnabled","errorMessage":"`Astro.cache` is not available because the cache feature is not enabled. To use caching, configure a cache provider in your Astro config under `cache`.","messagePattern":"`Astro\\.cache` is not available because the cache feature is not enabled\\. To use caching, configure a cache provider in your Astro config under `cache`\\.","errorType":"exception","errorClass":"AstroError","httpStatus":null,"severity":"error","filePath":"packages/astro/src/core/cache/runtime/noop.ts","lineNumber":70,"sourceCode":"\t\t\t\t'`cache.set()` was called but caching is not enabled. Configure a cache provider in your Astro config under `cache` to enable caching.',\n\t\t\t);\n\t\t}\n\t}\n\n\tset(): void {\n\t\tthis.#warn();\n\t}\n\n\tget tags(): string[] {\n\t\treturn [];\n\t}\n\n\tget options(): Readonly<CacheOptions> {\n\t\treturn EMPTY_OPTIONS;\n\t}\n\n\tasync invalidate(): Promise<void> {\n\t\tthrow new AstroError(CacheNotEnabled);\n\t}\n}\n","sourceCodeStart":52,"sourceCodeEnd":73,"githubUrl":"https://github.com/withastro/astro/blob/52e6c34790cc8ac4e69e6135ace06049867e5c4a/packages/astro/src/core/cache/runtime/noop.ts#L52-L73","documentation":"Astro exposes `Astro.cache` in components and middleware. When no cache provider is configured, Astro installs a `DisabledAstroCache` whose `set()` only logs a one-time warning (so libraries can call it unconditionally), but `invalidate()` throws `CacheNotEnabled` because the caller expects purging to actually work. Configure a provider under `cache` in astro.config to get a real cache implementation.","triggerScenarios":"Awaiting `Astro.cache.invalidate()` (or a tag-based invalidate) in middleware, actions, or route code while astro.config has no `cache: { provider: ... }` entry. Only `invalidate()` throws; `set()` silently warns and the `tags`/`options` getters return empty values.","commonSituations":"Copy-pasting cache invalidation code from the docs into a project that never enabled the cache; the adapter that normally injects a provider is not installed in this environment; writing tag-based invalidation before turning the feature on.","solutions":["Add a cache provider to astro.config: `cache: { provider: { entrypoint: 'astro/cache/memory' } }` or your adapter's provider entrypoint.","If your platform adapter supplies the provider (Netlify/Vercel/etc.), install and configure that adapter.","If you cannot enable caching, gate the call: `if (Astro.cache.enabled) await Astro.cache.invalidate()` — the disabled implementation reports `enabled === false`."],"exampleFix":"// before\nawait Astro.cache.invalidate(); // throws CacheNotEnabled without a provider\n\n// after — guard on the runtime flag\nif (Astro.cache.enabled) {\n  await Astro.cache.invalidate();\n}\n\n// astro.config.mjs — make invalidation actually work\nexport default defineConfig({\n  cache: { provider: { entrypoint: 'astro/cache/memory' } },\n});","handlingStrategy":"type-guard","validationCode":"// The cache API reports whether a real provider is installed\nif (Astro.cache.enabled) {\n  await Astro.cache.invalidate(['products']);\n} else {\n  console.warn('Cache not configured; skipping invalidation.');\n}","typeGuard":"// CacheLike implementations expose `enabled`; real providers set it to true,\n// DisabledAstroCache and NoopAstroCache set it to false\nfunction isCacheEnabled(cache: { enabled: boolean }): cache is { enabled: true } {\n  return cache.enabled === true;\n}","tryCatchPattern":"try {\n  await Astro.cache.invalidate();\n} catch (err) {\n  if (err instanceof Error && err.name === 'CacheNotEnabled') return; // degrade gracefully\n  throw err;\n}","preventionTips":["Add `cache: { provider: { entrypoint: ... } }` to astro.config in every environment whose code calls cache APIs.","Treat caching as an optional enhancement: gate all invalidation on `Astro.cache.enabled`.","Add a CI smoke test that exercises cache invalidation against the same provider used in production."],"tags":["cache","configuration","astro-cache"],"backgroundTag":"feature-not-enabled","analyzedSha":"52e6c34790cc8ac4e69e6135ace06049867e5c4a","analyzedAt":"2026-08-18T18:48:03.901Z","contentChangedAt":"2026-08-18T18:48:03.901Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}