{"record":{"id":"9067ea2d9c9917f5","repo":"withastro/astro","slug":"unknownfilesystemerror-9067ea","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":"error_code","errorClass":"AstroError","httpStatus":null,"severity":"error","filePath":"packages/astro/src/content/mutable-data-store.ts","lineNumber":134,"sourceCode":"\t\t\t\t\t\tconst id = imageSrcToImportId(assetImport, typedEntry.filePath);\n\t\t\t\t\t\tif (id) {\n\t\t\t\t\t\t\tthis.#assetImports.add(id);\n\t\t\t\t\t\t}\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\t}\n\n\tasync writeAssetImports(filePath: PathLike) {\n\t\tthis.#assetsFile = filePath;\n\t\tthis.#rebuildAssetImports();\n\n\t\tif (this.#assetImports.size === 0) {\n\t\t\ttry {\n\t\t\t\tawait this.#writeFileAtomic(filePath, 'export default new Map();');\n\t\t\t} catch (err) {\n\t\t\t\tthrow new AstroError(AstroErrorData.UnknownFilesystemError, { cause: err });\n\t\t\t}\n\t\t}\n\n\t\tif (!this.#assetsDirty && existsSync(filePath)) {\n\t\t\treturn;\n\t\t}\n\t\t// Import the assets, with a symbol name that is unique to the import id. The import\n\t\t// for each asset is an object with path, format and dimensions.\n\t\t// We then export them all, mapped by the import id, so we can find them again in the build.\n\t\tconst imports: Array<string> = [];\n\t\tconst exports: Array<string> = [];\n\t\t// Sort asset imports to ensure deterministic output across builds\n\t\tconst sortedAssetImports = [...this.#assetImports].sort();\n\t\tsortedAssetImports.forEach((id, index) => {\n\t\t\tconst symbol = `__ASTRO_IMAGE_IMPORT_${index}`;\n\t\t\timports.push(`import ${symbol} from ${JSON.stringify(id)};`);\n\t\t\texports.push(`[${JSON.stringify(id)}, ${symbol}]`);\n\t\t});","sourceCodeStart":116,"sourceCodeEnd":152,"githubUrl":"https://github.com/withastro/astro/blob/d081033d5fe8e8a68c4bbbad4af9d2deb9c74bca/packages/astro/src/content/mutable-data-store.ts#L116-L152","documentation":"Thrown by MutableDataStore.writeAssetImports when writing the empty-asset-imports placeholder file ('export default new Map();') fails. The underlying fs error is attached as cause. This path runs when the store has zero asset imports and tries to persist the empty default export.","triggerScenarios":"The atomic write helper (#writeFileAtomic) fails on the assets file path: permission denied, EACCES, disk full, the target directory was deleted, or the path is read-only.","commonSituations":"Build output directory (.astro/) is read-only or missing; running the build as a user without write permission to the project; CI environments where .astro was made immutable; disk-full or inode exhaustion; antivirus/SELinux blocking writes.","solutions":["Check the cause field on the thrown error for the real OS error code (EACCES, ENOSPC, ENOENT).","Ensure the .astro/ directory exists and is writable: rm -rf .astro and re-run.","Run the build with adequate filesystem permissions and free disk space.","If in CI, verify the working directory is writable and not on a read-only mount."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"import { existsSync, accessSync, constants } from 'node:fs';\nimport { dirname } from 'node:path';\nfunction ensureWritableDir(p: string) {\n  const dir = dirname(p);\n  if (!existsSync(dir)) throw new Error(`missing dir ${dir}`);\n  accessSync(dir, constants.W_OK);\n}","typeGuard":null,"tryCatchPattern":"try {\n  await store.writeAssetImports(assetsPath);\n} catch (e) {\n  const cause = e instanceof AstroError ? e.cause : e;\n  if (cause && /EACCES|ENOENT|ENOSPC/.test((cause as Error).message)) {\n    // permissions/space/path issue - surface actionable hint\n  }\n  throw e;\n}","preventionTips":["Verify .astro/ exists and is writable before building.","Run builds under a user that owns the cache directory.","Free disk/inode headroom before large builds.","Avoid deleting .astro mid-build."],"tags":["filesystem","content-collections","data-store","build","permissions"],"backgroundTag":null,"analyzedSha":"d081033d5fe8e8a68c4bbbad4af9d2deb9c74bca","analyzedAt":"2026-08-12T13:37:29.035Z","schemaVersion":2},"datasetVersion":"2026-08-12T18:17:37.767Z"}