{"record":{"id":"fe9c62d6ae6eb15e","repo":"withastro/astro","slug":"failed-to-write-lock-file-message","errorCode":null,"errorMessage":"Failed to write lock file: ${message}","messagePattern":"Failed to write lock file: (.+?)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/astro/src/core/dev/lockfile.ts","lineNumber":122,"sourceCode":"\t} catch {\n\t\treturn null;\n\t}\n}\n\n/**\n * Write the lock file to disk.\n */\nexport function writeLockFile(root: URL, data: LockFileData, command: ServerCommand = 'dev'): void {\n\tconst lockFileURL = getLockFileURL(root, command);\n\tconst dirPath = fileURLToPath(new URL('.astro/', root));\n\ttry {\n\t\tif (!existsSync(dirPath)) {\n\t\t\tmkdirSync(dirPath, { recursive: true });\n\t\t}\n\t\twriteFileSync(lockFileURL, serializeLockFile(data), 'utf-8');\n\t} catch (err) {\n\t\tconst message = err instanceof Error ? err.message : String(err);\n\t\tthrow new Error(`Failed to write lock file: ${message}`);\n\t}\n}\n\n/**\n * Remove the lock file from disk. No-op if it doesn't exist.\n */\nexport function removeLockFile(root: URL, command: ServerCommand = 'dev'): void {\n\tconst lockFileURL = getLockFileURL(root, command);\n\ttry {\n\t\tunlinkSync(lockFileURL);\n\t} catch (err: any) {\n\t\t// ENOENT means the file doesn't exist, which is fine.\n\t\t// Any other error (permissions, etc.) should be surfaced.\n\t\tif (err?.code !== 'ENOENT') {\n\t\t\tthrow err;\n\t\t}\n\t}\n}","sourceCodeStart":104,"sourceCodeEnd":140,"githubUrl":"https://github.com/withastro/astro/blob/d081033d5fe8e8a68c4bbbad4af9d2deb9c74bca/packages/astro/src/core/dev/lockfile.ts#L104-L140","documentation":"`writeLockFile` serializes the dev/build lock file to `<root>/.astro/`; if directory creation or `writeFileSync` fails (permissions, disk full, read-only FS, path issues), the error is caught and re-thrown as a plain `Error` prefixed 'Failed to write lock file:'. This wraps low-level FS errors with actionable context.","triggerScenarios":"Running `astro dev`/`astro build` in a directory where `.astro/` cannot be created or written: read-only filesystem, insufficient permissions, EBUSY on Windows, ENOSPC, or a path collision. The `catch` at `lockfile.ts:122` wraps any thrown error.","commonSituations":"CI with a read-only source mount; Docker `COPY` without writable layer; a previous crash leaving a locked file on Windows; disk-full environments; running from a tarball extraction that dropped write bits.","solutions":["Ensure the project root (and `.astro/`) is writable by the current user.","Free disk space if ENOSPC; on Windows, close processes locking the file.","In CI/Docker, mount or create a writable `.astro/` directory.","Run `astro sync` once in a build step that has write access, then copy artifacts."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"const fs = require('fs'); const dir = path.join(root, '.astro'); try { fs.accessSync(dir, fs.constants.W_OK); } catch { /* ensure writable or create */ }","typeGuard":"function isDirWritable(p) { try { fs.accessSync(p, fs.constants.W_OK); return true; } catch { return false; } }","tryCatchPattern":"try { writeLockFile(root, data); } catch (e) { if (/Failed to write lock file/.test(e.message)) { /* handle FS/permission issue */ } else throw e; }","preventionTips":["Ensure the project root is writable in CI/Docker.","Pre-warm .astro/ via `astro sync` in a writable build step.","Avoid read-only source mounts for dev/build environments."],"tags":["filesystem","dev","build","permissions"],"backgroundTag":null,"analyzedSha":"d081033d5fe8e8a68c4bbbad4af9d2deb9c74bca","analyzedAt":"2026-08-12T13:37:29.035Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}