What causes "Unknown content collection error." in withastro/astro?

Check that the file at the path in the error message still exists and is readable.

withastro/astro · error · AstroError

UnknownContentCollectionError

UnknownContentCollectionError

Error message

Unknown content collection error.

What it means

A catch-all error thrown when `fs.promises.readFile` fails while reading a content entry file inside `getContentEntryType` processing. The original filesystem error is attached as `cause`. This is an unexpected-error wrapper: the file was expected to exist and be readable, so a failure here indicates a race condition, permission issue, or the file was deleted between discovery and read.

Source

Thrown at packages/astro/src/content/utils.ts:829

	collection,
	generatedSlug,
	contentEntryType,
	fileUrl,
	fs,
}: {
	fs: typeof fsMod;
	id: string;
	collection: string;
	generatedSlug: string;
	fileUrl: URL;
	contentEntryType: Pick<ContentEntryType, 'getEntryInfo'>;
}) {
	let contents: string;
	try {
		contents = await fs.promises.readFile(fileUrl, 'utf-8');
	} catch (e) {
		// File contents should exist. Raise unexpected error as "unknown" if not.
		throw new AstroError(AstroErrorData.UnknownContentCollectionError, { cause: e });
	}
	const { slug: frontmatterSlug } = await contentEntryType.getEntryInfo({
		fileUrl,
		contents,
	});
	return parseEntrySlug({ generatedSlug, frontmatterSlug, id, collection });
}

function getExtGlob(exts: string[]) {
	return exts.length === 1
		? // Wrapping {...} breaks when there is only one extension
			exts[0]
		: `{${exts.join(',')}}`;
}

function globWithUnderscoresIgnored(relContentDir: string, exts: string[]): string[] {
	const extGlob = getExtGlob(exts);
	const contentDir = relContentDir.length > 0 ? appendForwardSlash(relContentDir) : relContentDir;

View on GitHub (pinned to d081033d5f)

Solutions

Check that the file at the path in the error message still exists and is readable.
Restart `astro dev` to re-scan the content directory.
Fix filesystem permissions on the content directory (`chmod -R+r src/content`).
Remove or fix broken symlinks in the content directory.
If using a remote/cloud-synced filesystem, ensure sync is complete before building.

Defensive patterns

Strategy: try-catch

Validate before calling

import { existsSync, accessSync, constants } from 'fs';
function ensureReadable(filePath: string) {
  if (!existsSync(filePath)) throw new Error(`Missing: ${filePath}`);
  accessSync(filePath, constants.R_OK);
}

Try / catch

try {
  const data = await getEntry('blog', 'post');
} catch (e) {
  if (e instanceof Error && /Unknown content collection error/.test(e.message)) {
    console.error('Filesystem issue — check file exists:', e.cause);
  }
  throw e;
}

Prevention

Avoid editing content files while astro dev is running; use a save hook instead.
Ensure content directories have read permissions in CI.
Run a file-existence check in pre-build scripts for critical entries.

When it happens

Trigger: `getEntryInfo` is called for a content entry whose file URL was previously resolved. The `readFile` call throws (ENOENT, EACCES, EISDIR, etc.), and the error is wrapped with `UnknownContentCollectionError` as the top-level AstroError and the filesystem error as `cause`.

Common situations: A file is deleted or moved while `astro dev` is running and HMR hasn't caught up. Filesystem permissions deny read access to the content directory. A symlink loop or broken symlink points to a non-existent target. An editor's safe-save temporarily removes the file.

Related errors

AI-assisted analysis of withastro/astro@d081033d5f (2026-08-12). Data as JSON: /api/errors/24b9feb43bfea64a. Report an issue: GitHub.