What causes "unable to close file: %v" in vitessio/vitess?

Inspect the wrapped error and check disk space and filesystem health on the tablet-dir volume.

unable to close file: %v

Error message

unable to close file: %v

What it means

Thrown by createStateFile when closing the just-created restore state file descriptor fails. Rare — typically indicates a filesystem/I/O error (some filesystems surface ENOSPC or write-back errors at close) or an interrupted file operation.

Source

Thrown at go/vt/mysqlctl/backupengine.go:767

		return err
	}
	return nil
}

// create restore state file
func createStateFile(cnf *Mycnf) error {
	// if we start writing content to this file:
	// change RD_ONLY to RDWR
	// change Create to Open
	// rename func to openStateFile
	// change to return a *File
	fname := filepath.Join(cnf.TabletDir(), RestoreState)
	fd, err := os2.Create(fname)
	if err != nil {
		return fmt.Errorf("unable to create file: %v", err)
	}
	if err = fd.Close(); err != nil {
		return fmt.Errorf("unable to close file: %v", err)
	}
	return nil
}

// delete restore state file
func removeStateFile(cnf *Mycnf) error {
	fname := filepath.Join(cnf.TabletDir(), RestoreState)
	if err := os.Remove(fname); err != nil {
		return fmt.Errorf("unable to delete file: %v", err)
	}
	return nil
}

// RestoreWasInterrupted tells us whether a previous restore
// was interrupted and we are now retrying it
func RestoreWasInterrupted(cnf *Mycnf) bool {
	name := filepath.Join(cnf.TabletDir(), RestoreState)
	_, err := os.Stat(name)

View on GitHub (pinned to 01a25a7d17)

Solutions

Inspect the wrapped error and check disk space and filesystem health on the tablet-dir volume.
Re-run the restore once storage is healthy — state file creation is retried on the next attempt.
Check dmesg/storage logs for I/O errors on the host.

Defensive patterns

Strategy: retry

Validate before calling

if err := checkDiskSpace(cnf.TabletDir(), minFreeBytes); err != nil {
    return err
}

Try / catch

if err := restore(); err != nil {
    if strings.Contains(err.Error(), "unable to close file") {
        // verify filesystem health/disk space, then retry the restore once
        return retryRestore()
    }
    return err
}

Prevention

Monitor disk space and I/O errors on hosts running restores.
Use local/reliable storage for tablet dirs rather than flaky network filesystems.
Re-run restore on transient storage failures after verifying disk health.

When it happens

Trigger: os2.Create succeeded but fd.Close() returns a non-nil error during the restore preparation step.

Common situations: Full disk where write-back fails at close; underlying storage errors (NFS/EBS hiccups); extremely rare local-disk edge cases.

Related errors

AI-assisted analysis of vitessio/vitess@01a25a7d17 (2026-09-01). Data as JSON: /api/errors/d0606d4ef06ae22b. Report an issue: GitHub.