{"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/52e6c34790cc8ac4e69e6135ace06049867e5c4a/packages/astro/src/prefetch/vite-plugin-prefetch.ts#L11-L47","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"// before - astro.config.mjs\nexport default defineConfig({ output: 'static' }); // code imports 'astro:prefetch'\n\n// after\nexport default defineConfig({ output: 'static', prefetch: true });","handlingStrategy":"validation","validationCode":null,"typeGuard":null,"tryCatchPattern":null,"preventionTips":["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."],"tags":["prefetch","config","virtual-module"],"backgroundTag":"optional-feature-not-enabled","analyzedSha":"52e6c34790cc8ac4e69e6135ace06049867e5c4a","analyzedAt":"2026-08-18T18:48:03.901Z","contentChangedAt":"2026-08-18T18:48:03.901Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}