withastro/astro · error · AstroError

UnknownFilesystemError

UnknownFilesystemError

Error message

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

What it means

Thrown by FsFontFileContentResolver.resolve when reading a local absolute-path font file via readFileSync fails for any reason. The file contents are used only to generate a deterministic id/filename for the font. Non-absolute (HTTP) URLs are returned as-is and never trigger this. The original error is attached as cause with code UnknownFilesystemError.

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 d081033d5f)

Solutions

1. Verify the absolute path in the error exists and is readable by the build user.
2. Check permissions on the file and parent directories (chmod/read access).
3. If the file moved, update the font source path in the config.
4. Confirm any symlinks resolve to a real file.
5. Inspect the `cause` for the precise errno (ENOENT, EACCES, etc.).

Example fix

// before
import url from '../../static/fonts/MyFont.woff2'; // path no longer exists

// after
import url from '../../public/fonts/MyFont.woff2'; // correct location

import { accessSync, constants } from 'node:fs';
import { isAbsolute } from 'node:path';
function readableFontPath(url: string): boolean {
  if (!isAbsolute(url)) return true; // remote, skipped
  try { accessSync(url, constants.R_OK); return true; } catch { return false; }
}

try { resolver.resolve(url); }
catch (e) {
  if (e instanceof AstroError && e.code === 'UnknownFilesystemError') {
    // log e.cause.errno, fix permissions/path, then retry
  }
}

When it happens

Trigger: Calling resolve(url) where url is an absolute filesystem path that does not exist, is not readable by the process, or hits a permission/quota error during readFileSync. Remote URLs (not isAbsolute) skip the read entirely and return url unchanged.

Common situations: A local font path resolved to a missing file, the build running as a user without read permission, a path on a network mount that is unmounted, or a symlink that points nowhere.

Related errors

• UnknownFilesystemError
• CannotDetermineWeightAndStyleFromFontFile
• UnknownFilesystemError
• Failed to write lock file: ${message}
• CannotFetchFontFile

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