withastro/astro · error · AstroError

UnknownContentCollectionError

UnknownContentCollectionError

Error message

Collection "${collection}" is a live collection. Use getLiveCollection() instead of getCollection().

What it means

Astro distinguishes persisted content collections from live collections (defined with `defineLiveCollection`, type 'live', fetched at request time). Calling `getCollection()` on a live collection throws this UnknownContentCollectionError variant, steering you to `getLiveCollection()`, because live entries are never in the data store `getCollection()` reads.

Solutions

Switch the call to `getLiveCollection('products')` (entries expose `data` and live-specific fields; no `render()`).
If the collection should be build-time persisted after all, define it with `defineCollection` + a normal loader.
In shared code, branch on the collection type or accept a fetcher so both collection kinds can use it.

Example fix

// before
const products = await getCollection('products');

// after
const products = await getLiveCollection('products');

Defensive patterns

Strategy: type-guard

Validate before calling

// src/lib/collections.ts — keep one source of truth for which collections are live
import { getCollection, getLiveCollection } from 'astro:content';

const LIVE_COLLECTIONS = new Set(['products']); // keep in sync with live.config.ts

export function isLiveCollection(name: string): boolean {
  return LIVE_COLLECTIONS.has(name);
}

export async function getAnyCollection(name: string) {
  return isLiveCollection(name) ? getLiveCollection(name) : getCollection(name);
}

Type guard

import type { CollectionKey } from 'astro:content';

type LiveKeys = 'products'; // derive from your live config
type StoredKeys = Exclude<CollectionKey, LiveKeys>;

// overloads make the wrong call a compile error
export function get(name: LiveKeys): Promise<ReturnType<typeof getLiveCollection>>;
export function get(name: StoredKeys): Promise<ReturnType<typeof getCollection>>;
export function get(name: string) {
  return name === 'products' ? getLiveCollection(name) : getCollection(name);
}

Try / catch

try {
  const items = await getCollection('products');
} catch (err) {
  if ((err as any)?.code === 'UnknownContentCollectionError' && /live collection/.test(err.message)) {
    const items = await getLiveCollection('products'); // fall back to the correct API
  } else throw err;
}

Prevention

Wrap every collection access in small named helpers so the live/stored split lives in one file.
When adopting live collections, grep the codebase for getCollection(/getEntry( and update each call.

When it happens

Trigger: `await getCollection('products')` where `products` is defined via `defineLiveCollection({ type: 'live', loader: ... })` in src/content/config.ts (or live.config.ts).

Common situations: Converting a collection to the experimental live-collections feature and forgetting to update queries; shared components/utilities that call getCollection for any collection name passed in; upgrading Astro versions where a collection changed to live.

Related errors

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

Appendix: source

Thrown at packages/astro/src/content/runtime.ts:107

				error as Error,
			),
		};
	}
}

export function createGetCollection({
	liveCollections,
	logger,
}: {
	liveCollections: LiveCollectionConfigMap;
	logger: AstroLogger;
}) {
	return async function getCollection(
		collection: string,
		filter?: ((entry: any) => unknown) | Record<string, unknown>,
	) {
		if (collection in liveCollections) {
			throw new AstroError({
				...AstroErrorData.UnknownContentCollectionError,
				message: `Collection "${collection}" is a live collection. Use getLiveCollection() instead of getCollection().`,
			});
		}

		const hasFilter = typeof filter === 'function';
		const store = await globalDataStore.get();
		if (await store.hasCollection(collection)) {
			// @ts-expect-error	virtual module
			const { default: imageAssetMap } = await import('astro:asset-imports');

			const result = [];
			for (const rawEntry of await store.values<DataEntry>(collection)) {
				const data = resolveEntryData(rawEntry, imageAssetMap);

				let entry = {
					...rawEntry,
					data,

View on GitHub (pinned to e294953aa8)