{"record":{"id":"c1a724e56a365667","repo":"ipfs/kubo","slug":"unexpected-error-while-checking-writeablility-of-r","errorCode":null,"errorMessage":"unexpected error while checking writeablility of repo root: %s","messagePattern":"unexpected error while checking writeablility of repo root: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cmd/ipfs/kubo/init.go","lineNumber":188,"sourceCode":"\t\tif err := addDefaultAssets(out, repoRoot); err != nil {\n\t\t\treturn err\n\t\t}\n\t}\n\n\treturn pinEmptyDir(repoRoot)\n}\n\nfunc checkWritable(dir string) error {\n\t_, err := os.Stat(dir)\n\tif err == nil {\n\t\t// dir exists, make sure we can write to it\n\t\ttestfile := filepath.Join(dir, \"test\")\n\t\tfi, err := os.Create(testfile)\n\t\tif err != nil {\n\t\t\tif os.IsPermission(err) {\n\t\t\t\treturn fmt.Errorf(\"%s is not writeable by the current user\", dir)\n\t\t\t}\n\t\t\treturn fmt.Errorf(\"unexpected error while checking writeablility of repo root: %s\", err)\n\t\t}\n\t\tfi.Close()\n\t\treturn os.Remove(testfile)\n\t}\n\n\tif os.IsNotExist(err) {\n\t\t// dir doesn't exist, check that we can create it\n\t\treturn os.Mkdir(dir, 0o775)\n\t}\n\n\tif os.IsPermission(err) {\n\t\treturn fmt.Errorf(\"cannot write to %s, incorrect permissions\", err)\n\t}\n\n\treturn err\n}\n\nfunc addDefaultAssets(out io.Writer, repoRoot string) error {","sourceCodeStart":170,"sourceCodeEnd":206,"githubUrl":"https://github.com/ipfs/kubo/blob/329838acdfafae224582930457efe80aa217afc0/cmd/ipfs/kubo/init.go#L170-L206","documentation":"Thrown by checkWritable when probing the existing repo dir fails with an unexpected (non-permission) OS error while trying to create the test file `<dir>/test`. This is the catch-all branch: anything other than EACCES/EPERM-style failures, e.g. ENOSPC, ENAMETOOLONG, EDQUOT, EROFS reported differently, or I/O errors. The underlying OS error is embedded in the message.","triggerScenarios":"os.Create(\"<dir>/test\") fails with an error for which os.IsPermission(err) is false while the dir exists: disk full (ENOSPC), quota exceeded (EDQUOT), path too long (ENAMETOOLONG), I/O error on a failing disk, or path is actually a non-directory special file.","commonSituations":"Full disk or quota when initializing into a data volume; failing or detached network mounts; IPFS_PATH set to a very deep path exceeding NAME_MAX; device errors on unhealthy storage.","solutions":["Read the embedded OS error in the message and address it: free disk space (`df -h`), raise quota, or shorten IPFS_PATH.","Check filesystem health (`dmesg`, `mount` output) if the error indicates I/O failure, and remount or replace the volume.","Retry init on a known-good writable directory: `export IPFS_PATH=$(mktemp -d) && ipfs init` to confirm the problem is with the original location."],"exampleFix":null,"handlingStrategy":"validation","validationCode":"var st syscall.Statfs_t\nif err := syscall.Statfs(repoDir, &st); err == nil {\n\tfree := st.Bavail * uint64(st.Bsize)\n\tif free < 256<<20 {\n\t\tlog.Fatalf(\"only %d bytes free on %s, free space before init\", free, repoDir)\n\t}\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Check free disk space and quota on the target volume before initializing large repos","Keep IPFS_PATH short and on a healthy local filesystem, not deep paths or flaky network mounts","Monitor disk health (SMART) on hosts that initialize large repos"],"tags":["filesystem","init","io"],"backgroundTag":"unexpected-filesystem-error","analyzedSha":"329838acdfafae224582930457efe80aa217afc0","analyzedAt":"2026-09-03T18:30:52.135Z","contentChangedAt":"2026-09-03T18:30:52.135Z","schemaVersion":2},"datasetVersion":"2026-09-11T00:17:11.886Z"}