benbjohnson/litestream · warning

sync temp meta file: %w

Error message

sync temp meta file: %w

What it means

Hydrator.saveMeta wraps tmp.Sync() failures as "sync temp meta file". fsync ensures the TXID survives a crash before the atomic rename; if the sync fails, the temp file is cleaned up and the meta is not published, so the next open re-hydrates.

Source

Thrown at vfs.go:1009

	tmpPath := tmp.Name()

	if _, err := fmt.Fprintf(tmp, "%d\n", txid); err != nil {
		if closeErr := tmp.Close(); closeErr != nil {
			h.logger.Warn("failed to close temp meta file during cleanup", "error", closeErr)
		}
		if removeErr := os.Remove(tmpPath); removeErr != nil {
			h.logger.Warn("failed to remove temp meta file during cleanup", "error", removeErr)
		}
		return fmt.Errorf("write hydration meta: %w", err)
	}
	if err := tmp.Sync(); err != nil {
		if closeErr := tmp.Close(); closeErr != nil {
			h.logger.Warn("failed to close temp meta file during cleanup", "error", closeErr)
		}
		if removeErr := os.Remove(tmpPath); removeErr != nil {
			h.logger.Warn("failed to remove temp meta file during cleanup", "error", removeErr)
		}
		return fmt.Errorf("sync temp meta file: %w", err)
	}
	if err := tmp.Close(); err != nil {
		if removeErr := os.Remove(tmpPath); removeErr != nil {
			h.logger.Warn("failed to remove temp meta file during cleanup", "error", removeErr)
		}
		return fmt.Errorf("close temp meta file: %w", err)
	}
	if err := os.Rename(tmpPath, h.metaPath()); err != nil {
		if removeErr := os.Remove(tmpPath); removeErr != nil {
			h.logger.Warn("failed to remove temp meta file during cleanup", "error", removeErr)
		}
		return fmt.Errorf("rename hydration meta: %w", err)
	}
	if err := syncDir(filepath.Dir(h.metaPath())); err != nil {
		return fmt.Errorf("sync hydration meta directory: %w", err)
	}
	return nil
}

View on GitHub (pinned to 4ed7a308f6)

Solutions

1. Check kernel logs (dmesg) for I/O errors on the backing device — treat EIO as a hardware/disk problem
2. Replace or remount the failing volume; move the hydration path to healthy local storage
3. Accept the degraded mode: without a saved meta, litestream simply re-hydrates fully on next start

if err := saveMeta(); err != nil && errors.Is(err, syscall.EIO) {
	// disk failing — evacuate volume and re-hydrate from replica
}

When it happens

Trigger: fsync returns EIO because the underlying disk is failing or was detached; ENOSPC-like metadata pressure on some filesystems; network filesystems that don't support reliable fsync returning errors.

Common situations: Failing disks reporting E_IO in dmesg; VM disks detached on the hypervisor side; FUSE/NFS mounts with flaky fsync support.

Understand the failure class

Background: "failed to write file", "Could not save figure", "Error saving remote file" — file write failed: causes and fixes across languages and libraries — this error's family across 38 libraries.

Related errors

• sync L0 file: %w
• sync ltx dir: %w
• sync before truncate: %w
• sync txid file: %w
• sync txid dir: %w

AI-assisted analysis of benbjohnson/litestream@4ed7a308f6 (2026-09-06). Data as JSON: /api/errors/ee96cdb5df2f241d. Report an issue: GitHub.