{"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/d081033d5fe8e8a68c4bbbad4af9d2deb9c74bca/packages/astro/src/assets/fonts/infra/fs-font-file-content-resolver.ts#L8-L30","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Verify the absolute path in the error exists and is readable by the build user.","Check permissions on the file and parent directories (chmod/read access).","If the file moved, update the font source path in the config.","Confirm any symlinks resolve to a real file.","Inspect the `cause` for the precise errno (ENOENT, EACCES, etc.)."],"exampleFix":"// before\nimport url from '../../static/fonts/MyFont.woff2'; // path no longer exists\n\n// after\nimport url from '../../public/fonts/MyFont.woff2'; // correct location","handlingStrategy":"validation","validationCode":"import { accessSync, constants } from 'node:fs';\nimport { isAbsolute } from 'node:path';\nfunction readableFontPath(url: string): boolean {\n  if (!isAbsolute(url)) return true; // remote, skipped\n  try { accessSync(url, constants.R_OK); return true; } catch { return false; }\n}","typeGuard":null,"tryCatchPattern":"try { resolver.resolve(url); }\ncatch (e) {\n  if (e instanceof AstroError && e.code === 'UnknownFilesystemError') {\n    // log e.cause.errno, fix permissions/path, then retry\n  }\n}","preventionTips":["Verify local font file paths exist and are readable before build.","Run the build with a user that has read access to font assets.","Avoid symlinks for font files; use real files."],"tags":["fonts","filesystem","permissions","build"],"backgroundTag":null,"analyzedSha":"d081033d5fe8e8a68c4bbbad4af9d2deb9c74bca","analyzedAt":"2026-08-12T13:37:29.035Z","schemaVersion":2},"datasetVersion":"2026-08-12T18:17:37.767Z"}