{"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/e294953aa8aadd98d5be92e60a03037b05dbdfd4/packages/astro/src/core/cache/runtime/cache.ts#L85-L121","documentation":"Astro.cache is backed by a provider supplied either by an adapter or by the cache config. The runtime object exists even without a provider, but cache operations — invalidate() here — throw CacheNotEnabled when no provider is configured, which is also the case in dev where caching is disabled and a noop runtime is installed.","triggerScenarios":"Calling Astro.cache.invalidate(...) or context.cache.invalidate(...) without cache: { provider: ... } in astro.config and without an adapter that injects a default provider; using any cache method during astro dev, where the noop runtime is active.","commonSituations":"Testing cache invalidation locally in dev; deploying with the static adapter (no cache provider) while the code assumes the node adapter's cache; enabling cache-related code paths before wiring the cache config.","solutions":["Configure a provider in astro.config: cache: { provider: '...' }, or use an adapter that ships a default cache provider.","Guard every call with the enabled flag: if (Astro.cache.enabled) { ... } — the interface exposes it for exactly this check.","In dev, treat caching as a no-op and skip invalidation logic, or verify behavior in a preview/build run where the provider is active."],"exampleFix":"// before\nawait Astro.cache.invalidate({ tags: ['posts'] });\n\n// after\nif (Astro.cache.enabled) {\n  await Astro.cache.invalidate({ tags: ['posts'] });\n}\n// and enable the feature in astro.config.mjs:\n// export default defineConfig({ cache: { provider: '...' } });","handlingStrategy":"type-guard","validationCode":"// Gate every cache interaction on the runtime flag\nif (Astro.cache.enabled) {\n  await Astro.cache.invalidate({ tags: ['posts'] });\n} else {\n  // dev or provider-less deploy: caching is a no-op here\n}","typeGuard":"const canInvalidate = (cache: { enabled: boolean }): boolean => cache.enabled;\n\n// usage\nif (canInvalidate(Astro.cache)) await Astro.cache.invalidate({ tags });","tryCatchPattern":null,"preventionTips":["Check Astro.cache.enabled (or context.cache.enabled) before any cache call — libraries are expected to.","Configure cache: { provider: ... } in astro.config or rely on an adapter that provides one.","Verify cache behavior in preview/production runs; dev intentionally runs without a provider."],"tags":["cache","configuration","runtime","feature-flag"],"backgroundTag":"feature-not-enabled","analyzedSha":"e294953aa8aadd98d5be92e60a03037b05dbdfd4","analyzedAt":"2026-08-18T18:48:03.901Z","contentChangedAt":"2026-08-18T18:48:03.901Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}