What causes "while syncing file: %s" in dgraph-io/dgraph?

Read the wrapped cause and file name; check dmesg/kern.log for I/O errors on that device.

while syncing file: %s

Error message

while syncing file: %s

What it means

fileSyncer.Close calls fsync on the underlying *os.File before closing; if Sync fails the error is wrapped as 'while syncing file: <name>'. This guarantees backup data actually hit disk; a failure means data durability is not guaranteed for that file.

Source

Thrown at worker/backup_handler.go:201

		return true
	})
}
func (h *fileHandler) CreateDir(path string) error {
	path = h.JoinPath(path)
	if err := os.MkdirAll(path, 0755); err != nil {
		return errors.Errorf("Create path failed to create path %s, got error: %v", path, err)
	}
	return nil
}

type fileSyncer struct {
	fp *os.File
}

func (fs *fileSyncer) Write(p []byte) (n int, err error) { return fs.fp.Write(p) }
func (fs *fileSyncer) Close() error {
	if err := fs.fp.Sync(); err != nil {
		return errors.Wrapf(err, "while syncing file: %s", fs.fp.Name())
	}
	err := fs.fp.Close()
	return errors.Wrapf(err, "while closing file: %s", fs.fp.Name())
}

func (h *fileHandler) CreateFile(path string) (io.WriteCloser, error) {
	path = h.JoinPath(path)
	fp, err := os.Create(path)
	return &fileSyncer{fp}, errors.Wrapf(err, "File handler failed to create file %s", path)
}

func (h *fileHandler) Rename(src, dst string) error {
	src = h.JoinPath(src)
	dst = h.JoinPath(dst)
	return os.Rename(src, dst)
}

// pathExist checks if a path (file or dir) is found at target.

View on GitHub (pinned to 759e242be6)

Solutions

Read the wrapped cause and file name; check dmesg/kern.log for I/O errors on that device.
Free disk space — fsync commonly surfaces ENOSPC not seen at write time.
If the device reports I/O errors, stop using it, re-mount or replace hardware, and restore from a known-good backup.
Retry the backup after fixing storage; the partially synced file must be considered corrupt/untrusted.

Example fix

// before
if err := fs.fp.Sync(); err != nil {
    return errors.Wrapf(err, "while syncing file: %s", fs.fp.Name())
}
// after
if err := fs.fp.Sync(); err != nil {
    os.Remove(fs.fp.Name()) // don't leave a possibly-corrupt backup
    return errors.Wrapf(err, "while syncing file: %s", fs.fp.Name())
}

Defensive patterns

Strategy: try-catch

Try / catch

if err := wc.Close(); err != nil {
    if strings.Contains(err.Error(), "while syncing file") {
        log.Printf("CRITICAL: backup file not durably synced: %v — treat as failed", err)
        os.Remove(backupPath)
        return err
    }
    return err
}

Prevention

Monitor disk space proactively; fsync failures often surface only at close.
Run SMART monitoring on backup storage.
Treat files whose Close() failed as invalid — never register them as backups.
Prefer local disks over flaky network mounts for backup staging.

When it happens

Trigger: fs.fp.Sync() returns an error — typically ENOSPC/EIO on writeback, EROFS, or device I/O errors during fsync of a backup file just written.

Common situations: Disk full discovered at fsync time; failing disk or controller; NFS reporting stale file handles; container storage driver errors.

Related errors

AI-assisted analysis of dgraph-io/dgraph@759e242be6 (2026-09-01). Data as JSON: /api/errors/2c8fd02865319f27. Report an issue: GitHub.