{"record":{"id":"43130f016f9e17c6","repo":"withastro/astro","slug":"you-need-to-enable-the-prefetch-astro-config-to","errorCode":null,"errorMessage":"You need to enable the `prefetch` Astro config to import `astro:prefetch`","messagePattern":"You need to enable the `prefetch` Astro config to import `astro:prefetch`","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/astro/src/prefetch/vite-plugin-prefetch.ts","lineNumber":29,"sourceCode":"\tconst prefetch = prefetchOption\n\t\t? typeof prefetchOption === 'object'\n\t\t\t? prefetchOption\n\t\t\t: {}\n\t\t: undefined;\n\n\t// Check against existing scripts as this plugin could be called multiple times\n\tif (prefetch && settings.scripts.every((s) => s.content !== prefetchCode)) {\n\t\t// Inject prefetch script to all pages\n\t\tsettings.scripts.push({\n\t\t\tstage: 'page',\n\t\t\tcontent: `import { init } from 'astro/virtual-modules/prefetch.js';init()`,\n\t\t});\n\t}\n\n\t// Throw a normal error instead of an AstroError as Vite captures this in the plugin lifecycle\n\t// and would generate a different stack trace itself through esbuild.\n\tconst throwPrefetchNotEnabledError = () => {\n\t\tthrow new Error('You need to enable the `prefetch` Astro config to import `astro:prefetch`');\n\t};\n\n\treturn {\n\t\tname: 'astro:prefetch',\n\t\tresolveId: {\n\t\t\tfilter: {\n\t\t\t\tid: new RegExp(`^${VIRTUAL_MODULE_ID}$`),\n\t\t\t},\n\t\t\thandler() {\n\t\t\t\tif (!prefetch) throwPrefetchNotEnabledError();\n\t\t\t\treturn RESOLVED_VIRTUAL_MODULE_ID;\n\t\t\t},\n\t\t},\n\t\tload: {\n\t\t\tfilter: {\n\t\t\t\tid: new RegExp(`^${RESOLVED_VIRTUAL_MODULE_ID}$`),\n\t\t\t},\n\t\t\thandler() {","sourceCodeStart":11,"sourceCodeEnd":47,"githubUrl":"https://github.com/withastro/astro/blob/d081033d5fe8e8a68c4bbbad4af9d2deb9c74bca/packages/astro/src/prefetch/vite-plugin-prefetch.ts#L11-L47","documentation":"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.","triggerScenarios":"Importing `astro:prefetch` (or `import 'astro:prefetch'`) in any module while `astro.config` has `prefetch: false` or omits `prefetch` entirely.","commonSituations":"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.","solutions":["Set `prefetch: true` (or a prefetch options object) in `astro.config.mjs`.","Remove the `astro:prefetch` import if you do not want the feature.","Conditionally import prefetch only in projects that enable it."],"exampleFix":"// before — code imports prefetch, config has no prefetch key\nimport { prefetch } from 'astro:prefetch'\n\n// after — enable in config\nexport default defineConfig({ prefetch: true })","handlingStrategy":"validation","validationCode":"function assertPrefetchEnabled(config) {\n  if (!config.prefetch) {\n    throw new Error('Enable `prefetch` in astro.config before importing astro:prefetch');\n  }\n}","typeGuard":"function prefetchIsEnabled(config) {\n  return !!config.prefetch;\n}","tryCatchPattern":"null","preventionTips":["Set prefetch: true in config before importing astro:prefetch.","Remove prefetch imports when you disable the feature.","Keep prefetch imports co-located with the config that enables them."],"tags":["prefetch","config","performance","vite"],"backgroundTag":null,"analyzedSha":"d081033d5fe8e8a68c4bbbad4af9d2deb9c74bca","analyzedAt":"2026-08-12T13:37:29.035Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}