{"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":188,"sourceCode":"\t\t\t\tif (typedEntry.deferredRender && typedEntry.filePath) {\n\t\t\t\t\tconst id = contentModuleToId(typedEntry.filePath);\n\t\t\t\t\tif (id) {\n\t\t\t\t\t\tthis.#moduleImports.set(typedEntry.filePath, id);\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":170,"sourceCodeEnd":206,"githubUrl":"https://github.com/withastro/astro/blob/e294953aa8aadd98d5be92e60a03037b05dbdfd4/packages/astro/src/content/mutable-data-store.ts#L170-L206","documentation":"The mutable data store persists generated asset-import modules (e.g. .astro/assets-imports.mjs) using an atomic temp-file-plus-rename write. When the store has zero asset imports and writing the empty `export default new Map();` stub fails, the raw filesystem error is wrapped in AstroError code UnknownFilesystemError with the original error attached as `cause`.","triggerScenarios":"Any OS-level failure writing into the .astro directory: EACCES/EPERM (wrong ownership or read-only dir), ENOSPC (full disk), EBUSY/EPERM on rename (file locked by antivirus or a sync client), or a read-only filesystem in a container.","commonSituations":"Running `astro dev`/`astro build` once under sudo so .astro is root-owned; Docker/CI containers running as a non-root user without write access to the project dir; OneDrive/Dropbox locking generated files; full disks during large builds.","solutions":["Inspect `error.cause.code` (EACCES, EPERM, ENOSPC, EBUSY) — the real reason is never in the AstroError message itself.","Fix ownership and clear the generated dir: `sudo chown -R $(whoami) .astro` then `rm -rf .astro` and rebuild.","In containers/CI, ensure the user can write the project directory (volume permissions, `user` in docker-compose).","Free disk space or exclude the project folder from antivirus/sync tools if rename locks persist."],"exampleFix":"# before: .astro left root-owned or locked, build fails with UnknownFilesystemError\nsudo chown -R \"$(whoami)\" . .astro\nrm -rf .astro\npnpm astro build","handlingStrategy":"try-catch","validationCode":"import { access, constants } from 'node:fs/promises';\nimport { mkdtemp } from 'node:fs/promises';\n\nasync function canWriteProjectDir(root: string): Promise<boolean> {\n  const probe = await mkdtemp(join(root, '.write-probe-'));\n  await rm(probe, { recursive: true });\n  return true;\n}","typeGuard":"import { isAstroError } from 'astro/errors';\n\nconst isFilesystemError = (err: unknown): err is { code: string } => {\n  const cause = (err as any)?.cause ?? err;\n  return typeof cause?.code === 'string';\n};","tryCatchPattern":"try {\n  await runAstroBuild(); // programmatic build/sync that writes .astro\n} catch (err) {\n  if (isAstroError(err) && (err as any).code === 'UnknownFilesystemError') {\n    const cause = (err as any).cause;\n    if (['EACCES', 'EPERM'].includes(cause?.code)) {\n      // fix ownership of .astro / project dir, then retry once\n    } else if (cause?.code === 'ENOSPC') {\n      // free disk space, then retry\n    } else if (cause?.code === 'EBUSY') {\n      // another process holds the file: stop duplicate dev servers / AV scan, retry after backoff\n    } else {\n      throw err;\n    }\n  } else throw err;\n}","preventionTips":["Never run astro under sudo; if you did, chown .astro back to your user.","In CI/Docker, run as a user with write access to the project directory.","Exclude the project (at least .astro) from antivirus and sync clients.","Run one Astro process per checkout."],"tags":["content-collections","filesystem","permissions","dev-server"],"backgroundTag":"file-write-permission-denied","analyzedSha":"e294953aa8aadd98d5be92e60a03037b05dbdfd4","analyzedAt":"2026-08-18T18:48:03.901Z","contentChangedAt":"2026-08-18T18:48:03.901Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}