withastro/astro · error · Error

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

Error message

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

What it means

The `astro:prefetch` virtual module is only resolved when `prefetch` is enabled in `astro.config`. The plugin deliberately throws a plain Error (not AstroError, to preserve Vite's stack trace) if `prefetch` is falsy at `resolveId` time, because the prefetch runtime and injected script are not initialized when the feature is off.

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

Solutions

1. Set `prefetch: true` (or a prefetch options object) in `astro.config.mjs`.
2. Remove the `astro:prefetch` import if you do not want the feature.
3. Conditionally import prefetch only in projects that enable it.

Example fix

// before — code imports prefetch, config has no prefetch key
import { prefetch } from 'astro:prefetch'

// after — enable in config
export default defineConfig({ prefetch: true })

function assertPrefetchEnabled(config) {
  if (!config.prefetch) {
    throw new Error('Enable `prefetch` in astro.config before importing astro:prefetch');
  }
}

function prefetchIsEnabled(config) {
  return !!config.prefetch;
}

null

When it happens

Trigger: Importing `astro:prefetch` (or `import 'astro:prefetch'`) in any module while `astro.config` has `prefetch: false` or omits `prefetch` entirely.

Common situations: Enabling prefetch imports in code but forgetting to enable the `prefetch` config; disabling prefetch config while leaving imports; copy-pasting prefetch code from a project where it was enabled.

Related errors

• MissingMiddlewareForInternationalization
• EnvPrefixConflictsWithSecret
• i18nNotEnabled
• ServerOnlyModule
• CONTENT_TOO_LARGE

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