gastownhall/beads · error

failed to sync temp file: %w

Error message

failed to sync temp file: %w

What it means

atomicWriteFile calls tmp.Sync() to fsync the temp file's contents to disk before renaming, guaranteeing durability. This wraps a Sync failure; the temp file is cleaned up and the destination is left unchanged.

Source

Thrown at cmd/bd/backup_export.go:112

//     that must preserve a symlink's target should resolve path with
//     filepath.EvalSymlinks first (see cmd/bd/proxied_server.go).
func atomicWriteFile(path string, data []byte) error {
	dir := filepath.Dir(path)
	tmp, err := os.CreateTemp(dir, ".backup-tmp-*")
	if err != nil {
		return fmt.Errorf("failed to create temp file: %w", err)
	}
	tmpPath := tmp.Name()

	if _, err := tmp.Write(data); err != nil {
		_ = tmp.Close()
		_ = os.Remove(tmpPath)
		return fmt.Errorf("failed to write temp file: %w", err)
	}
	if err := tmp.Sync(); err != nil {
		_ = tmp.Close()
		_ = os.Remove(tmpPath)
		return fmt.Errorf("failed to sync temp file: %w", err)
	}
	if err := tmp.Close(); err != nil {
		_ = os.Remove(tmpPath)
		return fmt.Errorf("failed to close temp file: %w", err)
	}
	if err := os.Rename(tmpPath, path); err != nil {
		_ = os.Remove(tmpPath)
		return fmt.Errorf("failed to rename temp file: %w", err)
	}
	return nil
}

// runBackupExport performs a Dolt-native backup to .beads/backup/.
// Returns the updated state.
func runBackupExport(ctx context.Context, force bool) (*backupState, error) {
	dir, err := backupDir()
	if err != nil {
		return nil, err

View on GitHub (pinned to 71377f2769)

Solutions

1. Check kernel logs for I/O errors: dmesg | grep -i 'i/o error'.
2. If the workspace is on NFS/network storage, move it to local disk or a more reliable mount.
3. Run filesystem health checks (fsck) on the affected volume.
4. Retry after the storage issue is resolved; no corrupt state file will have been written.

Example fix

// shell
dmesg | tail   # look for I/O errors on the device holding .beads
# then move workspace to healthy local storage and retry

// fsync failures surface only at write time; validate storage health beforehand:
// dmesg | grep -i 'i/o error'  and ensure .beads is not on a flaky NFS mount

if err := saveBackupState(dir, state); err != nil {
    if strings.Contains(err.Error(), "sync temp file") {
        log.Printf("storage fsync failed; check disk/NFS health: %v", err)
        return err
    }
    return err
}

When it happens

Trigger: tmp.Sync() returns an error: underlying storage I/O error, failing disk, network filesystem (NFS/CIFS) that doesn't support fsync reliably, or device errors surfaced at flush time.

Common situations: Running .beads on flaky NFS mounts; failing SSD/HDD reporting errors under load; virtualized storage backends with fsync issues.

Understand the failure class

Background: Rust io::Error: what ErrorKind::NotFound, PermissionDenied, and InvalidData actually mean — from real OS failures to library fail-closed refusals — this error's family across 12 libraries.

Related errors

• failed to read backup state: %w
• failed to write temp file: %w
• failed to write issue %s: %w
• comparing sidecars %s and %s: %w
• comparing sidecar %s to %s: %w

AI-assisted analysis of gastownhall/beads@71377f2769 (2026-08-30). Data as JSON: /api/errors/fc3002e464b29fbb. Report an issue: GitHub.