What causes "Failed to write lock file: ${message}" in withastro/astro?

Fix ownership/permissions: `sudo chown -R $(whoami) .astro` or `chmod -R u+w .astro`.

withastro/astro · error · Error

Failed to write lock file

Error message

Failed to write lock file: ${message}

What it means

`writeLockFile` creates the `.astro/` directory and writes the dev/build session lock file with sync fs calls. Any failure from `mkdirSync`/`writeFileSync` (permissions, read-only mount, disk full, file held by another process) is caught and rethrown as a plain Error prefixed "Failed to write lock file:" with the underlying message.

Solutions

Fix ownership/permissions: `sudo chown -R $(whoami) .astro` or `chmod -R u+w .astro`.
Delete a stale or root-owned lock: `rm -rf .astro` (it is regenerated).
Ensure the project directory is writable in Docker/CI (do not mount it read-only).
Free disk space and avoid running multiple dev/build processes against the same root simultaneously.

Example fix

# before
astro dev   # Failed to write lock file: EACCES: permission denied

# after
rm -rf .astro
chmod u+w .
astro dev

Defensive patterns

Strategy: validation

Validate before calling

// Preflight before starting dev/build: .astro must be writable
import { accessSync, constants, mkdirSync } from 'node:fs';
mkdirSync('.astro', { recursive: true });
try {
  accessSync('.astro', constants.W_OK);
} catch {
  console.error('.astro directory is not writable — fix permissions or the mount.');
  process.exit(1);
}

Prevention

Mount the project directory read-write in Docker/CI, or write `.astro` to a writable location via root.
Never run the dev server under sudo; it leaves root-owned files behind.
Run one dev/build process per project root at a time.

When it happens

Trigger: The `.astro` directory or lock file is not writable: EACCES/EPERM from ownership mismatch, a read-only bind mount in Docker/CI, ENOSPC when the disk is full, or a lock file held open by another process.

Common situations: Running the dev server in a container with a read-only project volume; an earlier `sudo astro dev` left root-owned `.astro`; two processes racing on the same root; CI runners with full disks.

Understand the failure class

Background: "Permission denied" / "Failed to write" file errors: why a library can't write its files to disk (EACCES, EPERM, ENOSPC) and how to fix them — this error's family across 43 libraries.

Related errors

AI-assisted analysis of withastro/astro@157c500c38 (2026-08-18). Data as JSON: /api/errors/fe9c62d6ae6eb15e. Report an issue: GitHub.

Appendix: source

Thrown at packages/astro/src/core/dev/lockfile.ts:175

	} catch {
		return null;
	}
}

/**
 * Write the lock file to disk.
 */
export function writeLockFile(root: URL, data: LockFileData, command: ServerCommand = 'dev'): void {
	const lockFileURL = getLockFileURL(root, command);
	const dirPath = fileURLToPath(new URL('.astro/', root));
	try {
		if (!existsSync(dirPath)) {
			mkdirSync(dirPath, { recursive: true });
		}
		writeFileSync(lockFileURL, serializeLockFile(data), 'utf-8');
	} catch (err) {
		const message = err instanceof Error ? err.message : String(err);
		throw new Error(`Failed to write lock file: ${message}`);
	}
}

/**
 * Remove the lock file from disk. No-op if it doesn't exist.
 */
export function removeLockFile(root: URL, command: ServerCommand = 'dev'): void {
	const lockFileURL = getLockFileURL(root, command);
	try {
		unlinkSync(lockFileURL);
	} catch (err: any) {
		// ENOENT means the file doesn't exist, which is fine.
		// Any other error (permissions, etc.) should be surfaced.
		if (err?.code !== 'ENOENT') {
			throw err;
		}
	}
}

View on GitHub (pinned to 157c500c38)