{"record":{"id":"417999336cc1846b","repo":"withastro/astro","slug":"unknownfilesystemerror","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/infra/fs-font-file-content-resolver.ts","lineNumber":26,"sourceCode":"\t#readFileSync: ReadFileSync;\n\n\tconstructor({ readFileSync }: { readFileSync: ReadFileSync }) {\n\t\tthis.#readFileSync = readFileSync;\n\t}\n\n\tresolve(url: string): string {\n\t\tif (!isAbsolute(url)) {\n\t\t\t// HTTP URLs are enough\n\t\t\treturn url;\n\t\t}\n\t\ttry {\n\t\t\t// We only use the file content for the id generation to ensure\n\t\t\t// deterministic output filenames regardless of the project's location\n\t\t\t// on disk. The absolute path is excluded so that the same font file\n\t\t\t// produces the same hash across different checkout directories.\n\t\t\treturn this.#readFileSync(url);\n\t\t} catch (cause) {\n\t\t\tthrow new AstroError(AstroErrorData.UnknownFilesystemError, { cause });\n\t\t}\n\t}\n}\n","sourceCodeStart":8,"sourceCodeEnd":30,"githubUrl":"https://github.com/withastro/astro/blob/52e6c34790cc8ac4e69e6135ace06049867e5c4a/packages/astro/src/assets/fonts/infra/fs-font-file-content-resolver.ts#L8-L30","documentation":"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).","triggerScenarios":"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.","commonSituations":"Paths resolved against a different cwd in CI; files missing from the deployed build context; Windows path handling when building in a Linux container.","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."],"exampleFix":"# before — absolute path that only exists on one machine\nurl: '/home/me/design/fonts/inter.woff2'\n\n# after — path relative to the project\nurl: './src/assets/fonts/inter.woff2'","handlingStrategy":"validation","validationCode":"import fs from 'node:fs';\n// run before build: every local font path must exist and be readable\nfor (const p of localFontPaths) {\n  fs.accessSync(p, fs.constants.R_OK); // throws ENOENT/EACCES early with a clear path\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["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."],"tags":["fonts","filesystem","build","ci"],"backgroundTag":"file-read-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"}