kopia/kopia · warning

error closing cache marker file

Error message

error closing cache marker file

What it means

WriteCacheMarker finishes with f.Close(); a non-nil close error is wrapped as "error closing cache marker file". On some filesystems Close is where write-back errors surface, meaning the marker contents may not have actually been flushed to stable storage.

Solutions

1. Treat the marker as unwritten: remove the cache directory and retry after checking the volume.
2. Verify disk space and device health (dmesg, SMART) on the cache volume.
3. Move the cache from network/removable storage to local disk.
4. Retry the operation once the volume is healthy; the marker is recreated automatically.

Example fix

// before
cache on /mnt/nfs-cache -> error closing cache marker file: input/output error
// after
kopia cache set --cache-directory ~/.cache/kopia  # local disk

// ensure the volume is local/reliable before caching
if fi, err := os.Stat(dir); err != nil || !fi.IsDir() {
    return errors.New("cache path must be an existing local directory")
}

if err := cachedir.WriteCacheMarker(dir, false); err != nil {
    if strings.Contains(err.Error(), "error closing cache marker file") {
        log.Warnf("marker close failed (write-back error on %s): %v", dir, err)
        // remove the suspect cache dir and recreate on local storage
        _ = os.RemoveAll(dir)
    }
    return err
}

When it happens

Trigger: WriteCacheMarker when f.Close() returns an error: deferred write-back failures (ENOSPC/EIO surfaced at close), network volume connection lost mid-operation, or filesystem-level errors on removable media.

Common situations: NFS/SMB cache mounts dropped mid-write; full disk where buffered writes only fail at flush/close; flaky external drives holding the cache.

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

• error creating cache marker
• unable to write cachedir marker contents
• unexpected cache marker error
• can't close tmp file
• error adding content to cache

AI-assisted analysis of kopia/kopia@82495e54b5 (2026-09-07). Data as JSON: /api/errors/224a2b2caacce6c8. Report an issue: GitHub.

Appendix: source

Thrown at internal/cachedir/cachedir.go:56

	if err == nil && st.Size() >= int64(len(cacheDirMarkerContents)) {
		// ok
		return nil
	}

	if err != nil && !os.IsNotExist(err) {
		return errors.Wrap(err, "unexpected cache marker error")
	}

	f, err := os.Create(markerFile) //nolint:gosec
	if err != nil {
		return errors.Wrap(err, "error creating cache marker")
	}

	if _, err := f.WriteString(cacheDirMarkerContents); err != nil {
		return errors.Wrap(err, "unable to write cachedir marker contents")
	}

	return errors.Wrap(f.Close(), "error closing cache marker file")
}

View on GitHub (pinned to 82495e54b5)