ipfs/kubo · error

unexpected error while checking writeablility of repo root:

Error message

unexpected error while checking writeablility of repo root: %s

What it means

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.

Source

Thrown at cmd/ipfs/kubo/init.go:188

		if err := addDefaultAssets(out, repoRoot); err != nil {
			return err
		}
	}

	return pinEmptyDir(repoRoot)
}

func checkWritable(dir string) error {
	_, err := os.Stat(dir)
	if err == nil {
		// dir exists, make sure we can write to it
		testfile := filepath.Join(dir, "test")
		fi, err := os.Create(testfile)
		if err != nil {
			if os.IsPermission(err) {
				return fmt.Errorf("%s is not writeable by the current user", dir)
			}
			return fmt.Errorf("unexpected error while checking writeablility of repo root: %s", err)
		}
		fi.Close()
		return os.Remove(testfile)
	}

	if os.IsNotExist(err) {
		// dir doesn't exist, check that we can create it
		return os.Mkdir(dir, 0o775)
	}

	if os.IsPermission(err) {
		return fmt.Errorf("cannot write to %s, incorrect permissions", err)
	}

	return err
}

func addDefaultAssets(out io.Writer, repoRoot string) error {

View on GitHub (pinned to 329838acdf)

Solutions

1. Read the embedded OS error in the message and address it: free disk space (`df -h`), raise quota, or shorten IPFS_PATH.
2. Check filesystem health (`dmesg`, `mount` output) if the error indicates I/O failure, and remount or replace the volume.
3. Retry init on a known-good writable directory: `export IPFS_PATH=$(mktemp -d) && ipfs init` to confirm the problem is with the original location.

var st syscall.Statfs_t
if err := syscall.Statfs(repoDir, &st); err == nil {
	free := st.Bavail * uint64(st.Bsize)
	if free < 256<<20 {
		log.Fatalf("only %d bytes free on %s, free space before init", free, repoDir)
	}
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• %s is not writeable by the current user
• cannot write to %s, incorrect permissions
• init: seeding init docs failed: %s
• flushing %s: %w
• copying binary to stash: %w

AI-assisted analysis of ipfs/kubo@329838acdf (2026-09-03). Data as JSON: /api/errors/c1a724e56a365667. Report an issue: GitHub.