withastro/astro · error · AstroError

UnknownFilesystemError

UnknownFilesystemError

Error message

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

What it means

Thrown during the fonts Vite plugin build close hook when creating the client output directory for fonts fails. After confirming a non-serve build, it computes the assets dir and calls mkdirSync(fontsDir, { recursive: true }); any error from that mkdir is wrapped as UnknownFilesystemError with the original cause.

Source

Thrown at packages/astro/src/assets/fonts/vite-plugin-fonts.ts:369

			},
		},
		async buildEnd() {
			// Run once during the build, no matter how many environments there are
			if (built) {
				return;
			}
			if (sync || !settings.config.fonts?.length || this.environment.config.command === 'serve') {
				cleanup();
				return;
			}

			try {
				const dir = getClientOutputDirectory(settings);
				const fontsDir = new URL(`.${assetsDir}`, dir);
				try {
					mkdirSync(fontsDir, { recursive: true });
				} catch (cause) {
					throw new AstroError(AstroErrorData.UnknownFilesystemError, { cause });
				}
				if (fontFileById) {
					logger.info(
						'assets',
						`Copying fonts (${fontFileById.size} file${fontFileById.size === 1 ? '' : 's'})...`,
					);
					await Promise.all(
						Array.from(fontFileById.entries()).map(async ([id, associatedData]) => {
							const data = await fontFetcher!.fetch({ id, ...associatedData });
							try {
								writeFileSync(new URL(id, fontsDir), data);
							} catch (cause) {
								throw new AstroError(AstroErrorData.UnknownFilesystemError, { cause });
							}
						}),
					);
				}
			} finally {

View on GitHub (pinned to d081033d5f)

Solutions

1. Confirm the build output directory is writable and not on a read-only filesystem.
2. Free disk space or raise the storage quota if ENOSPC.
3. Check permissions on the configured outDir (and assetsDir) — the build user needs write+create access.
4. If in a container, ensure the mounted volume is writable.
5. Inspect the `cause` for the precise errno and path.

Example fix

// before - outDir on a read-only mount
build: { assetsDir: '/readonly/assets' }

// after
build: { assetsDir: 'dist/assets' }

import { accessSync, constants } from 'node:fs';
import { dirname } from 'node:path';
function isDirWritable(p: string): boolean {
  try { accessSync(dirname(p), constants.W_OK); return true; } catch { return false; }
}

When it happens

Trigger: Triggered when writeBundle/closeBundle runs during `astro build`, settings.config.fonts has entries, the command is not 'serve', and mkdirSync fails on the client output fonts directory. Failures include ENOSPC, EACCES, EROFS (read-only filesystem), or a parent path that cannot be created.

Common situations: Building into a read-only output directory (container/CI), out of disk space, insufficient permissions on the dist folder, antivirus/lock on Windows, or a misconfigured outDir/assetsDir pointing at an invalid location.

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/0089c6ae6cde98e9. Report an issue: GitHub.