withastro/astro · error · AstroUserError

Live content collections must be defined in…

Error message

Live content collections must be defined in "src/live.config.ts" file. Check the loaders used in "${importerFilename ?? 'your content config file'}" to ensure you are not using a live loader to define a build-time content collection.

What it means

`defineCollection` rejects loader objects that expose `loadEntry`/`loadCollection` but no `load()` — the shape of a live loader. Live loaders only function inside `src/live.config.ts` with `defineLiveCollection`; wiring one into a build-time content collection produces a collection that can never sync, so an AstroUserError is thrown pointing at live.config.ts.

Solutions

1. Move the collection to `src/live.config.ts` and define it with `defineLiveCollection`
2. For a build-time collection, use a build-time loader (`glob()`, `file()`) that implements `load()`
3. Check the loader package's docs/exports to confirm whether it is a live or build-time loader before wiring it in

Example fix

// before — src/content.config.ts
export const collections = { docs: defineCollection({ loader: liveDbLoader() }) };

// after — src/live.config.ts
export const collections = { docs: defineLiveCollection({ loader: liveDbLoader() }) };

function isLiveLoader(loader) {
  return (
    typeof loader === 'object' &&
    loader !== null &&
    typeof loader.load !== 'function' &&
    (typeof loader.loadEntry === 'function' || typeof loader.loadCollection === 'function')
  );
}

if (isLiveLoader(config.loader)) {
  // belongs in src/live.config.ts with defineLiveCollection, not here
  throw new TypeError('live loader used in a build-time collection');
}
defineCollection(config);

When it happens

Trigger: `defineCollection({ loader: someLiveLoader })` in src/content.config.ts where the loader implements `loadEntry`/`loadCollection` but not `load`; loader libraries shipping live loaders being used in the build-time config.

Common situations: Trying a database/live loader in a build-time collection; migration experiments moving collections between configs; unclear loader package docs not stating which config file each loader belongs in.

Related errors

• A content collection is defined with legacy features (e.g…
• Collection loader for
• LiveContentConfigError
• PluginContentImportsError
• The glob() loader cannot be used for files in

AI-assisted analysis of withastro/astro@157c500c38 (2026-08-18). Data as JSON: /api/errors/454e353ee087fbbc. Report an issue: GitHub.

Appendix: source

Thrown at packages/astro/src/content/config.ts:204

			message: AstroErrorData.LiveContentConfigError.message(
				'Collections in a live config file must use `defineLiveCollection`.',
				importerFilename,
			),
		});
	}

	if ('loader' in config) {
		if (config.type && config.type !== CONTENT_LAYER_TYPE) {
			throw new AstroUserError(
				`A content collection is defined with legacy features (e.g. missing a \`loader\` or has a \`type\`). Check your collection definitions in ${importerFilename ?? 'your content config file'} to ensure that all collections are defined using the current properties.`,
			);
		}
		if (
			typeof config.loader === 'object' &&
			typeof config.loader.load !== 'function' &&
			('loadEntry' in config.loader || 'loadCollection' in config.loader)
		) {
			throw new AstroUserError(
				`Live content collections must be defined in "src/live.config.ts" file. Check the loaders used in "${importerFilename ?? 'your content config file'}" to ensure you are not using a live loader to define a build-time content collection.`,
			);
		}
		config.type = CONTENT_LAYER_TYPE;
	}
	if (!config.type) config.type = 'content';
	return config;
}

View on GitHub (pinned to 157c500c38)