kopia/kopia · error

error creating cache marker

Error message

error creating cache marker

What it means

WriteCacheMarker creates the marker file with os.Create after confirming it is missing or too small; failure is wrapped as "error creating cache marker". Without the marker the cache directory cannot be identified as a kopia cache, so the write fails deliberately.

Solutions

1. Make the cache directory writable by the process user (chown/chmod).
2. Free disk space or point the cache at a volume with room (kopia cache set --cache-directory ...).
3. If the marker path is a directory, remove it so os.Create can make the file.
4. On containers, mount a writable volume at the configured cache path.

Example fix

// before
$ kopia ... # error creating cache marker
// after
$ sudo chown -R $(id -u) ~/.cache/kopia
$ chmod u+w ~/.cache/kopia

if err := os.MkdirAll(dir, 0o700); err != nil {
    return errors.Wrap(err, "cache dir not writable")
}
testFile := filepath.Join(dir, ".write-test")
if err := os.WriteFile(testFile, []byte("x"), 0o600); err != nil {
    return errors.Wrap(err, "cache dir is not writable")
}
os.Remove(testFile)

if err := cachedir.WriteCacheMarker(dir, false); err != nil {
    if strings.Contains(err.Error(), "error creating cache marker") {
        return errors.Wrap(err, "check disk space and write permission on "+dir)
    }
    return err
}

When it happens

Trigger: WriteCacheMarker when os.Create(markerFile) fails: parent directory not writable, read-only filesystem, disk full, marker path is an existing directory, or quota exceeded.

Common situations: Cache directory on a read-only mount; running under a user without write access to the cache dir; disk-full conditions on small root filesystems; sandboxed/containerized environments with restricted writable paths.

Understand the failure class

Background: "Permission denied" / "Failed to write" file errors: why a library can't write its files to disk (EACCES, EPERM, ENOSPC) and how to fix them — this error's family across 43 libraries.

Related errors

• unable to write cache directory marker
• unable to write cachedir marker contents
• error adding blob
• error closing cache marker file
• error creating list cache directory

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

Appendix: source

Thrown at internal/cachedir/cachedir.go:49

	if cacheDir == "" {
		return nil
	}

	markerFile := filepath.Join(cacheDir, CacheDirMarkerFile)

	st, err := os.Stat(markerFile)
	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)