hashicorp/nomad · critical

failed creating alloc dir: %w

Error message

failed creating alloc dir: %w

What it means

If conf.AllocDir is set to a custom path, the client runs os.MkdirAll(conf.AllocDir, 0o711) during init. Any error aborts client startup with this message. The alloc dir holds working directories for all allocations on the node and must exist before any task starts.

Source

Thrown at client/client.go:743

	// Ensure host_volumes_dir config is not empty.
	if conf.HostVolumesDir == "" {
		conf = c.UpdateConfig(func(c *config.Config) {
			c.HostVolumesDir = filepath.Join(conf.StateDir, "host_volumes")
		})
	}

	// Ensure the alloc mounts dir exists if we are configured with a custom path.
	if conf.AllocMountsDir != "" {
		if err := os.MkdirAll(conf.AllocMountsDir, 0o711); err != nil {
			return fmt.Errorf("failed creating alloc mounts dir: %w", err)
		}
	}

	// Ensure the alloc dir exists if we are configured with a custom path.
	if conf.AllocDir != "" {
		if err := os.MkdirAll(conf.AllocDir, 0o711); err != nil {
			return fmt.Errorf("failed creating alloc dir: %w", err)
		}
	} else {
		// Otherwise make a temp directory to use.
		p, err := os.MkdirTemp("", "NomadClient")
		if err != nil {
			return fmt.Errorf("failed creating temporary directory for the AllocDir: %v", err)
		}

		p, err = filepath.EvalSymlinks(p)
		if err != nil {
			return fmt.Errorf("failed to find temporary directory for the AllocDir: %v", err)
		}

		// Change the permissions to have the execute bit
		if err := os.Chmod(p, 0o711); err != nil {
			return fmt.Errorf("failed to change directory permissions for the AllocDir: %v", err)
		}

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Pre-create alloc_dir with correct ownership and 0711 permissions for the user running Nomad.
2. Check the wrapped error (ENOENT/EACCES/ENOSPC/EEXIST-as-file) and correct the path, parent permissions, or disk state.
3. Point alloc_dir at a dedicated local writable volume reserved for Nomad.

Example fix

// before
client { alloc_dir = "/opt/nomad/alloc" }  // /opt/nomad owned by root:root 755
// after
sudo mkdir -p /opt/nomad/alloc && sudo chown -R nomad:nomad /opt/nomad && sudo chmod 711 /opt/nomad/alloc

func ensureAllocDir(p string) error {
    if fi, err := os.Stat(p); err == nil && !fi.IsDir() {
        return fmt.Errorf("%s is not a directory", p)
    }
    if err := os.MkdirAll(p, 0o711); err != nil {
        return err
    }
    f, err := os.CreateTemp(p, ".writetest")
    if err != nil { return err }
    f.Close(); os.Remove(f.Name())
    return nil
}

if err := clientInit(); err != nil {
    var pe *fs.PathError
    if errors.As(err, &pe) && strings.Contains(err.Error(), "failed creating alloc dir") {
        log.Printf("cannot create alloc dir %s: %v", pe.Path, pe.Err)
    }
}

When it happens

Trigger: client init with alloc_dir explicitly configured: os.MkdirAll(conf.AllocDir, 0o711) returns error.

Common situations: alloc_dir pointing to a path the nomad user cannot create (missing parents, no write access), a file already existing at the path, full or read-only data disk, or container storage driver limits.

Understand the failure class

Background: mkdir permission denied (EACCES): failed to create directory errors explained — this error's family across 32 libraries.

Related errors

• failed creating alloc mounts dir: %w
• failed to change directory permissions for the AllocDir: %v
• failed to create parent directories of %q: %w
• plugin not executable
• failed to snapshot %s: %w

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