withastro/astro · error · AstroError

CacheProviderNotFound

CacheProviderNotFound

Error message

Could not resolve the cache provider `${provider}`. Make sure the package is installed.

What it means

At dev/build startup the cache Vite plugin resolves your configured provider's `entrypoint`, using the project root's package.json as importer so adapter-provided providers (e.g. `astro/cache/memory`) resolve from your project's node_modules, not from astro core's location. If resolution fails or throws for an invalid specifier, `CacheProviderNotFound` is thrown with the provider's display name (`name` or entrypoint).

Solutions

1. Install the provider package: `npm install my-cache-provider`.
2. Verify it resolves from the project root: `node -e "console.log(require.resolve('my-cache-provider'))"` run at the root.
3. Fix spelling of the entrypoint or use the provider's `name` for a clearer error/identification.
4. For adapter-provided entrypoints, install and configure the matching adapter so the package lands in the project's node_modules.

Example fix

// before — package not installed
export default defineConfig({
  cache: { provider: { entrypoint: 'my-cache-provider' } },
});

# after
npm install my-cache-provider

export default defineConfig({
  cache: { provider: { entrypoint: 'my-cache-provider' } },
});

// Preflight: provider entrypoint must resolve from the project root,
// mirroring the importer the cache vite-plugin uses
import { createRequire } from 'node:module';
const require = createRequire(new URL('./package.json', import.meta.url));
try {
  require.resolve('my-cache-provider');
} catch {
  console.error('Configured cache provider is not installed. Run: npm install my-cache-provider');
  process.exit(1);
}

When it happens

Trigger: Setting `cache: { provider: { entrypoint: 'my-cache-provider' } }` when that package is not installed, is misspelled, publishes no valid exports map, or is not resolvable from the project root's node_modules (pnpm strictness, monorepo hoisting problems).

Common situations: Forgetting to `npm install` the provider package after adding the config; typo in the entrypoint string; using an adapter-provided provider entrypoint without the adapter installed; workspace where the package is only a transitive dependency.

Related errors

• `cache.set()` was called but caching is not enabled…
• CacheNotEnabled
• CacheNotEnabled
• CacheQueryConfigConflict
• AdapterSupportOutputMismatch

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

Appendix: source

Thrown at packages/astro/src/core/cache/vite-plugin.ts:52

		load: {
			filter: {
				id: new RegExp(`^${RESOLVED_VIRTUAL_CACHE_PROVIDER_ID}$`),
			},
			async handler() {
				const provider = normalizeCacheProviderConfig(providerConfig);
				// Use the project root as the importer so that adapter-provided
				// providers (e.g. astro/cache/memory) resolve from the project's
				// node_modules, not from astro core's location.
				const importerPath = fileURLToPath(new URL('package.json', settings.config.root));
				let resolved;
				try {
					resolved = await this.resolve(provider.entrypoint, importerPath);
				} catch {
					// Resolution can throw for invalid package specifiers
				}
				if (!resolved) {
					const displayName = provider.name ?? provider.entrypoint;
					throw new AstroError({
						...CacheProviderNotFound,
						message: CacheProviderNotFound.message(displayName),
					});
				}

				return {
					code: `import { default as _default } from '${resolved.id}';\nexport * from '${resolved.id}';\nexport default _default;`,
				};
			},
		},
	};
}

View on GitHub (pinned to 52e6c34790)