{"record":{"id":"3a8db81d2fcd0f57","repo":"kopia/kopia","slug":"error-creating-cache-marker","errorCode":null,"errorMessage":"error creating cache marker","messagePattern":"error creating cache marker","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/cachedir/cachedir.go","lineNumber":49,"sourceCode":"\tif cacheDir == \"\" {\n\t\treturn nil\n\t}\n\n\tmarkerFile := filepath.Join(cacheDir, CacheDirMarkerFile)\n\n\tst, err := os.Stat(markerFile)\n\tif err == nil && st.Size() >= int64(len(cacheDirMarkerContents)) {\n\t\t// ok\n\t\treturn nil\n\t}\n\n\tif err != nil && !os.IsNotExist(err) {\n\t\treturn errors.Wrap(err, \"unexpected cache marker error\")\n\t}\n\n\tf, err := os.Create(markerFile) //nolint:gosec\n\tif err != nil {\n\t\treturn errors.Wrap(err, \"error creating cache marker\")\n\t}\n\n\tif _, err := f.WriteString(cacheDirMarkerContents); err != nil {\n\t\treturn errors.Wrap(err, \"unable to write cachedir marker contents\")\n\t}\n\n\treturn errors.Wrap(f.Close(), \"error closing cache marker file\")\n}\n","sourceCodeStart":31,"sourceCodeEnd":58,"githubUrl":"https://github.com/kopia/kopia/blob/82495e54b584c1ef6073c9e1be048f57f8aef078/internal/cachedir/cachedir.go#L31-L58","documentation":"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.","triggerScenarios":"WriteCacheMarker when os.Create(markerFile) fails: parent directory not writable, read-only filesystem, disk full, marker path is an existing directory, or quota exceeded.","commonSituations":"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.","solutions":["Make the cache directory writable by the process user (chown/chmod).","Free disk space or point the cache at a volume with room (kopia cache set --cache-directory ...).","If the marker path is a directory, remove it so os.Create can make the file.","On containers, mount a writable volume at the configured cache path."],"exampleFix":"// before\n$ kopia ... # error creating cache marker\n// after\n$ sudo chown -R $(id -u) ~/.cache/kopia\n$ chmod u+w ~/.cache/kopia","handlingStrategy":"validation","validationCode":"if err := os.MkdirAll(dir, 0o700); err != nil {\n    return errors.Wrap(err, \"cache dir not writable\")\n}\ntestFile := filepath.Join(dir, \".write-test\")\nif err := os.WriteFile(testFile, []byte(\"x\"), 0o600); err != nil {\n    return errors.Wrap(err, \"cache dir is not writable\")\n}\nos.Remove(testFile)","typeGuard":null,"tryCatchPattern":"if err := cachedir.WriteCacheMarker(dir, false); err != nil {\n    if strings.Contains(err.Error(), \"error creating cache marker\") {\n        return errors.Wrap(err, \"check disk space and write permission on \"+dir)\n    }\n    return err\n}","preventionTips":["Pre-flight writable check (touch a temp file) before using a cache directory.","Monitor free space on the cache volume; alerts before it fills.","In containers, mount a writable volume at the configured cache path.","Run kopia as a user that owns the cache directory."],"tags":["cache","file-write","permissions","cachedir-marker","kopia"],"backgroundTag":"file-write-permission-denied","analyzedSha":"82495e54b584c1ef6073c9e1be048f57f8aef078","analyzedAt":"2026-09-07T20:35:21.689Z","contentChangedAt":"2026-09-07T20:35:21.689Z","schemaVersion":2},"datasetVersion":"2026-09-17T15:17:12.973Z"}