withastro/astro · error · AstroError

UnknownFilesystemError

UnknownFilesystemError

Error message

An unknown error occurred while reading or writing files to disk.

What it means

For local (absolute-path) font files, the fonts pipeline reads the file content to derive a deterministic cache id (fs-font-file-content-resolver.ts). The `readFileSync` failure — ENOENT, EACCES, EMFILE — is wrapped as `UnknownFilesystemError` with the Node error as `cause` (packages/astro/src/assets/fonts/infra/fs-font-file-content-resolver.ts:26).

Solutions

Print the resolved absolute path and check it exists: `node -e "console.log(require('fs').existsSync(path))"`.
Use project-relative URLs (e.g. `./src/assets/fonts/x.woff2`) so the path resolves against the project root instead of an absolute machine path.
Fix read permissions for the build user on that file and its directories.

Example fix

# before — absolute path that only exists on one machine
url: '/home/me/design/fonts/inter.woff2'

# after — path relative to the project
url: './src/assets/fonts/inter.woff2'

Defensive patterns

Strategy: validation

Validate before calling

import fs from 'node:fs';
// run before build: every local font path must exist and be readable
for (const p of localFontPaths) {
  fs.accessSync(p, fs.constants.R_OK); // throws ENOENT/EACCES early with a clear path
}

Prevention

Prefer project-relative URLs ('./src/assets/...') over absolute paths in fonts config.
Commit fonts to the repo rather than referencing machine-local absolute paths.
Validate the font file list in a prebuild script.

When it happens

Trigger: An absolute font path (as resolved by the config) that does not exist at build time, or exists but is not readable by the build process — wrong working directory, Docker volume mount differences, restrictive file modes.

Common situations: Paths resolved against a different cwd in CI; files missing from the deployed build context; Windows path handling when building in a Linux container.

Understand the failure class

Background: "failed to read file", EACCES, ENOENT and "could not read <path>" errors: when a program can't read a file from disk — this error's family across 49 libraries.

Related errors

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

Appendix: source

Thrown at packages/astro/src/assets/fonts/infra/fs-font-file-content-resolver.ts:26

	#readFileSync: ReadFileSync;

	constructor({ readFileSync }: { readFileSync: ReadFileSync }) {
		this.#readFileSync = readFileSync;
	}

	resolve(url: string): string {
		if (!isAbsolute(url)) {
			// HTTP URLs are enough
			return url;
		}
		try {
			// We only use the file content for the id generation to ensure
			// deterministic output filenames regardless of the project's location
			// on disk. The absolute path is excluded so that the same font file
			// produces the same hash across different checkout directories.
			return this.#readFileSync(url);
		} catch (cause) {
			throw new AstroError(AstroErrorData.UnknownFilesystemError, { cause });
		}
	}
}

View on GitHub (pinned to 52e6c34790)