hashicorp/nomad · error

insufficient write permissions in %s: %w

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.

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)

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

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.