lima-vm/lima · error

failed to write driver PID file: %w

Error message

failed to write driver PID file: %w

What it means

During external driver startup, lima writes the spawned driver process PID to a PID file in the instance directory so Stop can later find and signal the process. This error wraps the os.WriteFile failure: the process was already spawned, so it is killed and reaped before returning. It indicates a filesystem-level problem, not a driver problem.

Source

Thrown at pkg/driver/external/server/server.go:227

	if err != nil {
		return fmt.Errorf("failed to open external driver log file: %w", err)
	}
	defer func() {
		_ = logFile.Close()
	}()

	cmd := exec.CommandContext(ctx, extDriver.Path, "--inst-dir", instanceDir)
	cmd.Stderr = logFile
	if err := cmd.Start(); err != nil {
		return fmt.Errorf("failed to start external driver: %w", err)
	}

	pid := cmd.Process.Pid
	pidFilePath := driverPIDFilePath(instanceDir, extDriver.Name)
	if err := os.WriteFile(pidFilePath, []byte(strconv.Itoa(pid)), 0o644); err != nil {
		_ = cmd.Process.Kill()
		_, _ = cmd.Process.Wait()
		return fmt.Errorf("failed to write driver PID file: %w", err)
	}

	driverLogger := extDriver.Logger.WithField("driver", extDriver.Name)

	procExit := make(chan error, 1)
	go func() {
		procExit <- cmd.Wait()
		close(procExit)
		_ = os.Remove(pidFilePath)
	}()

	// Wait for the socket file to be created by the external driver.
	socketWaitCtx, socketWaitCancel := context.WithTimeout(ctx, 10*time.Second)
	defer socketWaitCancel()
	ticker := time.NewTicker(100 * time.Millisecond)
	defer ticker.Stop()
	for {
		select {

View on GitHub (pinned to dd909d0973)

Solutions

1. Check the instance directory exists and is writable (ls -ld ~/.lima/<instance>; create it if missing)
2. Free disk space on the volume holding LIMA_HOME
3. Fix permissions/ownership of the instance directory (chown/chmod)
4. If the directory was moved or LIMA_HOME changed, re-create the instance

Example fix

// before: starting with a non-existent instance dir
os.MkdirAll(instanceDir, 0o755) // missing -> os.WriteFile fails
// after: ensure the directory exists before Start
if err := os.MkdirAll(instanceDir, 0o755); err != nil {
	return fmt.Errorf("failed to prepare instance dir: %w", err)
}

info, err := os.Stat(instanceDir)
if err != nil || !info.IsDir() {
	return fmt.Errorf("instance dir %s missing or not a directory", instanceDir)
}
if err := os.MkdirAll(instanceDir, 0o755); err != nil {
	return err
}

if err := limactl.Start(inst); err != nil {
	var fsErr *os.PathError
	if errors.As(err, &fsErr) {
		// disk/permission issue on instance dir: repair and retry once
	}
	return err
}

When it happens

Trigger: CreateConfiguredDriver -> Start spawns the external driver binary successfully, then os.WriteFile(pidFilePath, ...) fails — e.g. instanceDir missing or deleted, disk full, read-only mount, or permission denied on the instance directory.

Common situations: LIMA_HOME on a read-only or full volume; instance directory removed by another process while starting; restrictive umask/permissions after copying instance dirs between users; macOS/Windows sync tools locking the directory.

Related errors

• external driver process exited before creating socket file
• external driver process exited before creating socket file:
• timed out waiting for external driver to create socket file
• instance %#q seems running (hint: remove %#q if the instance
• failed to create temp file: %w

AI-assisted analysis of lima-vm/lima@dd909d0973 (2026-09-01). Data as JSON: /api/errors/2ed905387c0e1795. Report an issue: GitHub.