What causes "failed to sync temporary file: %w" in nats-io/nats-server?

Check kernel logs (dmesg) and SMART status for disk I/O errors.

failed to sync temporary file: %w

Error message

failed to sync temporary file: %w

What it means

Returned when fsync on the temporary block file fails during a file-store message block update. The store calls tmpFD.Sync() to guarantee durability before renaming the temp file into place; failure aborts the update via errorCleanup, preserving the original block.

Source

Thrown at server/filestore.go:8067

			OriginalSize: uint64(originalSize),
		}
		buf = append(meta.MarshalMetadata(), buf...)
	}

	// Re-encrypt the block if necessary.
	if err = mb.encryptOrDecryptIfNeeded(buf); err != nil {
		return errorCleanup(err)
	}

	// Write the new block data (which might be compressed or encrypted) to the
	// temporary file.
	if n, err := tmpFD.Write(buf); err != nil {
		return errorCleanup(fmt.Errorf("failed to write to temporary file: %w", err))
	} else if n != len(buf) {
		return errorCleanup(fmt.Errorf("short write to temporary file (%d != %d)", n, len(buf)))
	}
	if err := tmpFD.Sync(); err != nil {
		return errorCleanup(fmt.Errorf("failed to sync temporary file: %w", err))
	}
	if err := tmpFD.Close(); err != nil {
		return errorCleanup(fmt.Errorf("failed to close temporary file: %w", err))
	}

	// Now replace the original file with the newly updated temp file.
	if err := os.Rename(tmpFN, origFN); err != nil {
		return fmt.Errorf("failed to move temporary file into place: %w", err)
	}

	// Since the message block might be retained in memory, make sure the
	// compression algorithm is up-to-date, since this will be needed when
	// compacting or truncating.
	mb.cmp = alg

	// Also update rbytes
	mb.rbytes = uint64(len(buf))

View on GitHub (pinned to 3a66a489d2)

Solutions

Check kernel logs (dmesg) and SMART status for disk I/O errors.
Verify the storage device is healthy and connected (especially cloud volumes/SAN).
Run filesystem check (fsck) on the affected volume after taking the server offline.
Retry the operation once storage is healthy; temp file is cleaned up automatically.

Example fix

// after: verify disk health
// smartctl -H /dev/sda && dmesg | grep -i "i/o error"

Defensive patterns

Strategy: retry

Try / catch

if err != nil && strings.Contains(err.Error(), "failed to sync temporary file") {
    // fsync failure: check storage health before retrying
    // alert ops and verify device via smartctl/dmesg
}

Prevention

Monitor disk SMART health and I/O error logs.
Use redundant/healthy storage for JetStream data.
Avoid storage backends that don't guarantee fsync semantics.
Set durability-aware alerts for fsync failures in server logs.

When it happens

Trigger: tmpFD.Sync() returns an error while syncing new block data to stable storage during a message block update (write/update path in filestore).

Common situations: Disk I/O errors, storage device failures/disconnections, virtualization or SAN issues where flush/fsync fails, or the underlying file becoming unavailable mid-update.

Related errors

AI-assisted analysis of nats-io/nats-server@3a66a489d2 (2026-09-02). Data as JSON: /api/errors/98e75c1a376b6cf4. Report an issue: GitHub.