{"record":{"id":"0089c6ae6cde98e9","repo":"withastro/astro","slug":"unknownfilesystemerror-0089c6","errorCode":"UnknownFilesystemError","errorMessage":"An unknown error occurred while reading or writing files to disk.","messagePattern":"An unknown error occurred while reading or writing files to disk\\.","errorType":"exception","errorClass":"AstroError","httpStatus":null,"severity":"error","filePath":"packages/astro/src/assets/fonts/vite-plugin-fonts.ts","lineNumber":371,"sourceCode":"\t\t\t},\n\t\t},\n\t\tasync buildEnd() {\n\t\t\t// Run once during the build, no matter how many environments there are\n\t\t\tif (built) {\n\t\t\t\treturn;\n\t\t\t}\n\t\t\tif (sync || !settings.config.fonts?.length || this.environment.config.command === 'serve') {\n\t\t\t\tcleanup();\n\t\t\t\treturn;\n\t\t\t}\n\n\t\t\ttry {\n\t\t\t\tconst dir = getClientOutputDirectory(settings);\n\t\t\t\tconst fontsDir = new URL(`.${assetsDir}`, dir);\n\t\t\t\ttry {\n\t\t\t\t\tmkdirSync(fontsDir, { recursive: true });\n\t\t\t\t} catch (cause) {\n\t\t\t\t\tthrow new AstroError(AstroErrorData.UnknownFilesystemError, { cause });\n\t\t\t\t}\n\t\t\t\tif (fontFileById) {\n\t\t\t\t\tlogger.info(\n\t\t\t\t\t\t'assets',\n\t\t\t\t\t\t`Copying fonts (${fontFileById.size} file${fontFileById.size === 1 ? '' : 's'})...`,\n\t\t\t\t\t);\n\t\t\t\t\tawait Promise.all(\n\t\t\t\t\t\tArray.from(fontFileById.entries()).map(async ([id, associatedData]) => {\n\t\t\t\t\t\t\tconst data = await fontFetcher!.fetch({ id, ...associatedData });\n\t\t\t\t\t\t\ttry {\n\t\t\t\t\t\t\t\twriteFileSync(new URL(id, fontsDir), data);\n\t\t\t\t\t\t\t} catch (cause) {\n\t\t\t\t\t\t\t\tthrow new AstroError(AstroErrorData.UnknownFilesystemError, { cause });\n\t\t\t\t\t\t\t}\n\t\t\t\t\t\t}),\n\t\t\t\t\t);\n\t\t\t\t}\n\t\t\t} finally {","sourceCodeStart":353,"sourceCodeEnd":389,"githubUrl":"https://github.com/withastro/astro/blob/52e6c34790cc8ac4e69e6135ace06049867e5c4a/packages/astro/src/assets/fonts/vite-plugin-fonts.ts#L353-L389","documentation":"During build, the fonts Vite plugin creates the client fonts output directory (`mkdirSync` under the client output dir + assets dir) before copying fetched font files (vite-plugin-fonts.ts:371). Any failure creating that directory — EACCES/EEXIST-on-a-file/EROFS — is wrapped as `UnknownFilesystemError` with the Node error as `cause`.","triggerScenarios":"Build output directory not writable (permissions, read-only filesystem), disk full, or a regular file already existing exactly where the fonts directory must be created (stale corrupted build output).","commonSituations":"CI containers running as non-root against mounted volumes; Docker read-only layers; builds after an interrupted run left odd artifacts in `dist`.","solutions":["Clean the output directory and rebuild: `rm -rf dist` (or your configured `outDir`).","Check write permissions and free disk space for the user running the build on the output directory.","Ensure the path where the fonts directory is created is a directory, not a leftover file with the same name."],"exampleFix":"# before — failing build on stale/locked output\nastro build\n\n# after — clean then rebuild\nrm -rf dist && astro build","handlingStrategy":"validation","validationCode":"import { access, constants } from 'node:fs/promises';\n// prebuild check: output dir writable and not blocked by a file\nawait access('./dist', constants.W_OK).catch(() => {\n  throw new Error('dist is not writable by the build user');\n});\nconst stats = await stat('./dist/client/_astro').catch(() => null);\nif (stats && !stats.isDirectory()) throw new Error('_astro exists but is not a directory');","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Start CI builds from a clean output dir (rm -rf dist or a fresh workspace).","Run the build as a user with write access to the workspace volume.","Watch disk quota alerts on CI runners before big builds."],"tags":["fonts","build","filesystem","ci"],"backgroundTag":"build-output-write-failed","analyzedSha":"52e6c34790cc8ac4e69e6135ace06049867e5c4a","analyzedAt":"2026-08-18T18:48:03.901Z","contentChangedAt":"2026-08-18T18:48:03.901Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}