hashicorp/nomad · error

insufficient write permissions in

Error message

insufficient write permissions in %s: %w

What it means

preflightChecks (raft-to-WAL migration) wraps the failure of writing a .permission-test probe file into the raft directory, proving the process lacks write permission on that directory before migration starts.

Solutions

  1. Grant the user running the migration write access to the raft directory (chown/chmod)
  2. Stop Nomad and run the migration as a user that owns the data directory
  3. Verify the filesystem is not mounted read-only
Defensive patterns

Strategy: try-catch

When it happens

Trigger: Thrown at helper/raftutil/migrate.go:199 when the library encounters an invalid state.

Common situations: See trigger scenarios.


AI-assisted analysis of hashicorp/nomad@482b49bf1a (2026-09-04). Data as JSON: /api/errors/9ecac081f9c1d399. Report an issue: GitHub.

Appendix: source

Thrown at helper/raftutil/migrate.go:199

func preflightChecks(boltPath, walDir, raftDir string) error {
	// Verify the BoltDB file exists.
	boltInfo, err := os.Stat(boltPath)
	if err != nil {
		return fmt.Errorf("BoltDB store not found at %s: %w", boltPath, err)
	}

	// Verify the WAL directory does not already exist.
	if _, err := os.Stat(walDir); err == nil {
		return fmt.Errorf(
			"WAL directory already exists at %s; remove it before retrying migration",
			walDir)
	}

	// Check write permissions on raft directory.
	testFile := filepath.Join(raftDir, ".permission-test")
	if err := os.WriteFile(testFile, []byte("test"), 0o600); err != nil {
		return fmt.Errorf("insufficient write permissions in %s: %w", raftDir, err)
	}
	os.Remove(testFile)

	// Check available disk space.
	usage, err := disk.Usage(raftDir)
	if err != nil {
		// Log warning but don't fail migration - disk space check is advisory.
		return fmt.Errorf("unable to check available disk space: %w", err)
	}
	availableSpace := usage.Free

	boltSize := uint64(boltInfo.Size())

	// Require at least the BoltDB size + minimum free space buffer.
	// WAL format is typically similar in size to BoltDB, but we add a buffer.
	requiredSpace := boltSize + minRequiredSpace
	if availableSpace < requiredSpace {
		return fmt.Errorf(

View on GitHub (pinned to 482b49bf1a)