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

When caching is not configured at all, Astro substitutes a `DisabledAstroCache` whose `set()` silently warns but whose `invalidate()` throws `CacheNotEnabled`. The design treats invalidation as a strict precondition: a caller that invalidates expects purging to actually happen, so a no-op would hide bugs. This is the dev/no-config counterpart to the provider-null case in `AstroCache`.

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 d081033d5f)

Solutions

1. Configure a cache provider in `astro.config` under the `cache` key.
2. Gate invalidation behind `Astro.cache.enabled` so disabled-cache environments skip it.
3. Use `astro/cache/memory` for local/dev and an adapter provider for production.

Example fix

// before
await Astro.cache.invalidate({ tags: ['home'] });

// after
if (Astro.cache.enabled) {
  await Astro.cache.invalidate({ tags: ['home'] });
}

if (!Astro.cache.enabled) { return; } // no-op in disabled mode

function cacheActive(cache) { return cache && cache.enabled === true; }

try {
  await Astro.cache.invalidate(...);
} catch (e) {
  if (e.code === 'CacheNotEnabled') { /* logging/no-op */ } else throw e;
}

When it happens

Trigger: Calling `Astro.cache.invalidate(...)` in a project with no `cache` entry in `astro.config`. The `DisabledAstroCache.invalidate` override at `noop.ts:70` always throws.

Common situations: Running a content site that uses `invalidate` in an endpoint but the user never added a cache provider; disabling cache temporarily for debugging while invalidation calls remain in shared middleware; integration code that assumes a cache is present.

Related errors

• CacheNotEnabled
• CacheQueryConfigConflict
• CacheProviderNotFound
• CannotOptimizeSvg
• RemoteImageNotAllowed

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