withastro/astro · error · Error

You need to enable the `prefetch` Astro config to import…

Error message

You need to enable the `prefetch` Astro config to import `astro:prefetch`

What it means

The `astro:prefetch` virtual module exposes the prefetch strategy programmatically. Its Vite plugin throws this plain Error (deliberately not an AstroError, so Vite's plugin lifecycle preserves the stack) when `astro:prefetch` is resolved but the `prefetch` option is not enabled in the Astro config.

Solutions

Enable prefetch in astro.config: `prefetch: true` (or `prefetch: { prefetchAll: false, defaultStrategy: 'hover' }`).
If you do not want prefetch, remove the `astro:prefetch` import from your code.
If the import comes from a dependency, enable prefetch or stop using that dependency.

Example fix

// before - astro.config.mjs
export default defineConfig({ output: 'static' }); // code imports 'astro:prefetch'

// after
export default defineConfig({ output: 'static', prefetch: true });

Defensive patterns

Strategy: validation

Prevention

Enable prefetch: true in astro.config before adding any astro:prefetch import.
When disabling prefetch to debug, grep the repo for astro:prefetch imports and remove them.
Check dependencies and copied template code for astro:prefetch usage before adding them to a project without prefetch.

When it happens

Trigger: Importing `astro:prefetch` in any module when astro.config has no `prefetch: true` (or a prefetch options object); disabling prefetch later while imports remain; adding a dependency or copied code that imports astro:prefetch to a project without prefetch enabled.

Common situations: Copying prefetch-related code from a template or the docs into a project that never turned prefetch on; starting with ClientRouter/ViewTransitions helpers that assume prefetch; toggling prefetch off to debug and forgetting the import.

Related errors

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

Appendix: source

Thrown at packages/astro/src/prefetch/vite-plugin-prefetch.ts:29

	const prefetch = prefetchOption
		? typeof prefetchOption === 'object'
			? prefetchOption
			: {}
		: undefined;

	// Check against existing scripts as this plugin could be called multiple times
	if (prefetch && settings.scripts.every((s) => s.content !== prefetchCode)) {
		// Inject prefetch script to all pages
		settings.scripts.push({
			stage: 'page',
			content: `import { init } from 'astro/virtual-modules/prefetch.js';init()`,
		});
	}

	// Throw a normal error instead of an AstroError as Vite captures this in the plugin lifecycle
	// and would generate a different stack trace itself through esbuild.
	const throwPrefetchNotEnabledError = () => {
		throw new Error('You need to enable the `prefetch` Astro config to import `astro:prefetch`');
	};

	return {
		name: 'astro:prefetch',
		resolveId: {
			filter: {
				id: new RegExp(`^${VIRTUAL_MODULE_ID}$`),
			},
			handler() {
				if (!prefetch) throwPrefetchNotEnabledError();
				return RESOLVED_VIRTUAL_MODULE_ID;
			},
		},
		load: {
			filter: {
				id: new RegExp(`^${RESOLVED_VIRTUAL_MODULE_ID}$`),
			},
			handler() {

View on GitHub (pinned to 52e6c34790)