withastro/astro · error · Error

No cached compile metadata found for "${id}". The main Astro

Error message

No cached compile metadata found for "${id}". The main Astro module "${filename}" should have compiled and filled the metadata first, before its virtual modules can be requested.

What it means

Astro's compiler caches per-file metadata (scripts, styles) in an in-memory map when a .astro module compiles, and virtual sub-modules such as file.astro?astro&type=style&index=0 or ...&type=script read from that cache. This error is thrown when such a virtual module is requested before its parent .astro file has compiled — including after the plugin forces a recompile of the parent. It signals a module-graph ordering problem, normally prevented because Vite loads the parent first.

Source

Thrown at packages/astro/src/vite-plugin-astro/index.ts:158

					// through the metadata from `astroFileToCompileMetadata`. It should always exist as Astro
					// modules are compiled first, then its virtual modules.
					const filename = normalizePath(normalizeFilename(parsedId.filename, config.root));
					let compileMetadata = astroFileToCompileMetadata.get(filename);
					if (!compileMetadata) {
						// If `compileMetadata` doesn't exist in dev, that means the virtual module may have been invalidated.
						// We try to re-compile the main Astro module (`filename`) first before retrieving the metadata again.
						if (server) {
							const code = await loadId(server.pluginContainer, filename);
							// `compile` should re-set `filename` in `astroFileToCompileMetadata`
							if (code != null) await compile(code, filename);
						}

						compileMetadata = astroFileToCompileMetadata.get(filename);
					}
					// If the metadata still doesn't exist, that means the virtual modules are somehow compiled first,
					// throw an error and we should investigate it.
					if (!compileMetadata) {
						throw new Error(
							`No cached compile metadata found for "${id}". The main Astro module "${filename}" should have ` +
								`compiled and filled the metadata first, before its virtual modules can be requested.`,
						);
					}

					switch (query.type) {
						case 'style': {
							if (typeof query.index === 'undefined') {
								throw new Error(`Requests for Astro CSS must include an index.`);
							}

							const result = compileMetadata.css[query.index];
							if (!result) {
								throw new Error(`No Astro CSS at index ${query.index}`);
							}

							// Register dependencies from preprocessing this style
							result.dependencies?.forEach((dep) => this.addWatchFile(dep));

View on GitHub (pinned to 52e6c34790)

Solutions

  1. Restart the dev server so the module graph is rebuilt in dependency order
  2. With the server stopped, delete node_modules/.vite (and .astro data), then start again
  3. If a custom plugin imports .astro?astro&type=... ids, import the parent .astro module instead and let Astro resolve its virtual sub-modules
  4. Report a minimal reproduction if it recurs on a clean cache with current versions
Defensive patterns

Strategy: try-catch

Try / catch

// custom plugins that touch astro virtual modules
try {
	const code = await loadId(server.pluginContainer, id);
} catch (err) {
	if (err instanceof Error && err.message.includes('No cached compile metadata')) {
		// import the parent .astro module first so it compiles, then retry the virtual id
		await loadId(server.pluginContainer, filename);
		return loadId(server.pluginContainer, id);
	}
	throw err;
}

Prevention

When it happens

Trigger: A custom plugin importing *.astro?astro&type=... URLs directly; deleting node_modules/.vite while the dev server is running; HMR after renaming or moving a .astro file leaving a stale graph; cached transforms from an older Astro version mixed with a newer one.

Common situations: Writing Vite plugins that scan or import Astro virtual modules; CI caches of .vite surviving an Astro upgrade; flaky HMR after large refactors with the dev server running.

Related errors

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