withastro/astro · error · AstroError

CacheProviderNotFound

CacheProviderNotFound

Error message

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

What it means

During Vite's dev-server module resolution, the cache plugin tries to resolve the provider's `entrypoint` specifier from the project's `node_modules` (using `package.json` at the project root as importer). If `this.resolve(...)` returns nothing or throws, the provider package is considered missing and Astro throws `CacheProviderNotFound`. This catches typo'd package names and uninstalled adapter-provided providers at startup.

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

Solutions

1. Install the missing provider package: `npm install <provider-entrypoint>`.
2. Confirm the `entrypoint` string matches the published package name exactly (check the provider's README).
3. For monorepos/pnpm, ensure the provider is a direct dependency of the project root, not only of a workspace package.
4. If the provider ships via an adapter, make sure the adapter is registered in `integrations` before referencing its provider.

Example fix

// before — astro.config.mjs
import { defineConfig } from 'astro/config';
export default defineConfig({
  cache: { provider: { name: 'redis', entrypoint: 'astro-cache-redis' } },
});

// after
npm install astro-cache-redis

const fs = require('fs');
const { createRequire } = require('module');
const req = createRequire(projectRoot + '/');
try { req.resolve(providerEntrypoint); } catch { throw new Error('Install provider: ' + providerEntrypoint); }

function providerResolvable(entrypoint, root) {
  const req = createRequire(root + '/package.json');
  try { req.resolve(entrypoint); return true; } catch { return false; }
}

When it happens

Trigger: Configuring `cache: { provider: { name: 'redis', entrypoint: 'astro-cache-redis' } }` when `astro-cache-redis` is not installed; referencing a provider exported by an adapter that hasn't been added; a monorepo where the provider lives in a workspace package not hoisted to the project root's `node_modules`.

Common situations: Forgetting to `npm install` the provider package; using a private/scoped provider that isn't published; pnpm strict-node-modules layout preventing resolution from the project root; typo in the entrypoint string.

Related errors

• CacheQueryConfigConflict
• CacheNotEnabled
• CacheNotEnabled
• `markdown.remarkPlugins`, `markdown.rehypePlugins`, and `mar
• CannotOptimizeSvg

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