{"record":{"id":"9a4fc7d7842acef0","repo":"withastro/astro","slug":"cachenotenabled","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/cache.ts","lineNumber":103,"sourceCode":"\n\tget tags(): string[] {\n\t\treturn [...this.#tags];\n\t}\n\n\t/**\n\t * Get the current cache options (read-only snapshot).\n\t * Includes all accumulated options: maxAge, swr, tags, etag, lastModified.\n\t */\n\tget options(): Readonly<CacheOptions> {\n\t\treturn {\n\t\t\t...this.#options,\n\t\t\ttags: this.tags,\n\t\t};\n\t}\n\n\tasync invalidate(input: InvalidateOptions | LiveDataEntry): Promise<void> {\n\t\tif (!this.#provider) {\n\t\t\tthrow new AstroError(CacheNotEnabled);\n\t\t}\n\t\tlet options: InvalidateOptions;\n\t\tif (isLiveDataEntry(input)) {\n\t\t\toptions = { tags: input.cacheHint?.tags ?? [] };\n\t\t} else {\n\t\t\toptions = input;\n\t\t}\n\t\treturn this.#provider.invalidate(options);\n\t}\n\n\t/** @internal */\n\t[APPLY_HEADERS](response: Response, request: Request): void {\n\t\tif (this.#disabled) return;\n\t\tconst finalOptions: CacheOptions = { ...this.#options, tags: this.tags };\n\t\tif (finalOptions.maxAge === undefined && !finalOptions.tags?.length) return;\n\n\t\tconst headers =\n\t\t\tthis.#provider?.setHeaders?.(finalOptions, request) ?? defaultSetHeaders(finalOptions);","sourceCodeStart":85,"sourceCodeEnd":121,"githubUrl":"https://github.com/withastro/astro/blob/d081033d5fe8e8a68c4bbbad4af9d2deb9c74bca/packages/astro/src/core/cache/runtime/cache.ts#L85-L121","documentation":"`Astro.cache.invalidate()` requires a backing cache provider to actually purge entries. The runtime `AstroCache` holds a `#provider` field that is `null` when no provider is wired up (e.g., cache disabled or misconfigured), and `invalidate` guards against a null provider by throwing `CacheNotEnabled`. This surfaces a missing-config problem at the call site rather than silently no-opping.","triggerScenarios":"Calling `Astro.cache.invalidate({ tags: ['post-123'] })` inside a route/action handler when the `cache` key is absent from `astro.config` or when the provider failed to load. The guard at `runtime/cache.ts:103` triggers because `this.#provider` is null.","commonSituations":"Local dev where caching is intentionally off but invalidation code runs in a shared util; deploying with the cache config behind an environment flag that evaluates false; an adapter that does not provide a cache provider.","solutions":["Add a cache provider to `astro.config`: `cache: { provider: memoryCache({ ... }) }` (or your adapter's provider).","Guard the call at the use site: `if (Astro.cache.enabled) await Astro.cache.invalidate(...)`.","Verify the provider package is installed and resolvable (see CacheProviderNotFound if resolution fails)."],"exampleFix":"// before\nawait Astro.cache.invalidate({ tags: ['posts'] });\n\n// after\nif (Astro.cache.enabled) {\n  await Astro.cache.invalidate({ tags: ['posts'] });\n}","handlingStrategy":"type-guard","validationCode":"if (!Astro.cache.enabled) { /* skip invalidation */ }","typeGuard":"function canInvalidate(cache) {\n  return cache && cache.enabled === true;\n}","tryCatchPattern":"try {\n  await Astro.cache.invalidate({ tags: ['x'] });\n} catch (e) {\n  if (e.code === 'CacheNotEnabled') { /* degrade gracefully */ } else throw e;\n}","preventionTips":["Always gate cache writes/invalidation behind Astro.cache.enabled.","Centralize cache operations in a helper that checks enabled first.","Ensure a cache provider is configured in every environment that runs invalidation code."],"tags":["cache","configuration","runtime"],"backgroundTag":null,"analyzedSha":"d081033d5fe8e8a68c4bbbad4af9d2deb9c74bca","analyzedAt":"2026-08-12T13:37:29.035Z","schemaVersion":2},"datasetVersion":"2026-08-12T18:17:37.767Z"}