withastro/astro · error · AstroError

CacheNotEnabled

CacheNotEnabled

Error message

`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`.

What it means

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.

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`.

Example fix

// before
await Astro.cache.invalidate(); // throws CacheNotEnabled without a provider

// after — guard on the runtime flag
if (Astro.cache.enabled) {
  await Astro.cache.invalidate();
}

// astro.config.mjs — make invalidation actually work
export default defineConfig({
  cache: { provider: { entrypoint: 'astro/cache/memory' } },
});

Defensive patterns

Strategy: type-guard

Validate before calling

// The cache API reports whether a real provider is installed
if (Astro.cache.enabled) {
  await Astro.cache.invalidate(['products']);
} else {
  console.warn('Cache not configured; skipping invalidation.');
}

Type guard

// CacheLike implementations expose `enabled`; real providers set it to true,
// DisabledAstroCache and NoopAstroCache set it to false
function isCacheEnabled(cache: { enabled: boolean }): cache is { enabled: true } {
  return cache.enabled === true;
}

Try / catch

try {
  await Astro.cache.invalidate();
} catch (err) {
  if (err instanceof Error && err.name === 'CacheNotEnabled') return; // degrade gracefully
  throw err;
}

Prevention

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.

When it happens

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

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

Related errors

AI-assisted analysis of withastro/astro@52e6c34790 (2026-08-18). Data as JSON: /api/errors/63e1c6a7e891219f. Report an issue: GitHub.

Appendix: source

Thrown at packages/astro/src/core/cache/runtime/noop.ts:70

				'`cache.set()` was called but caching is not enabled. Configure a cache provider in your Astro config under `cache` to enable caching.',
			);
		}
	}

	set(): void {
		this.#warn();
	}

	get tags(): string[] {
		return [];
	}

	get options(): Readonly<CacheOptions> {
		return EMPTY_OPTIONS;
	}

	async invalidate(): Promise<void> {
		throw new AstroError(CacheNotEnabled);
	}
}

View on GitHub (pinned to 52e6c34790)