hashicorp/nomad · error

Failed to mount shared directory for task: %w

Error message

Failed to mount shared directory for task: %w

What it means

During TaskDir.Build, when filesystem isolation is chroot and the task's shared directory is missing or empty, Nomad hard-links the alloc-level shared directory (SharedAllocDir) into the task's SharedTaskDir via linkDir. This error means that link operation failed, so the task would have no access to the shared allocation directory; Build aborts with this wrapped message.

Source

Thrown at client/allocdir/task_dir.go:157

	// Create the directories that should be in every task.
	for dir, perms := range TaskDirs {
		absdir := filepath.Join(t.Dir, dir)

		if err := allocMkdirAll(absdir, perms); err != nil {
			return err
		}
	}

	// Only link alloc dir into task dir for chroot fs isolation.
	// Image based isolation will bind the shared alloc dir in the driver.
	// If there's no isolation the task will use the host path to the
	// shared alloc dir.
	if fsi == fsisolation.Chroot {
		// If the path doesn't exist OR it exists and is empty, link it
		empty, _ := pathEmpty(t.SharedTaskDir)
		if !pathExists(t.SharedTaskDir) || empty {
			if err := linkDir(t.SharedAllocDir, t.SharedTaskDir, false); err != nil {
				return fmt.Errorf("Failed to mount shared directory for task: %w", err)
			}
			if err := linkDir(t.LogDir, filepath.Join(t.SharedTaskDir, "logs"), true); err != nil {
				return fmt.Errorf("Failed to mount shared directory for task: %w", err)
			}

		}
	}

	if err := t.MakeSecretsDirs(); err != nil {
		return err
	}

	// Build chroot if chroot filesystem isolation is going to be used
	if fsi == fsisolation.Chroot {
		if err := t.buildChroot(chroot); err != nil {
			return err
		}
	}

View on GitHub (pinned to 482b49bf1a)

Solutions

  1. Check the wrapped linkDir error: fix the underlying mkdir/link failure (permissions, missing parent dir, cross-device link).
  2. Ensure the client data_dir is on a single filesystem so hard links work.
  3. Stop the allocation, clean the stale task directory under client data_dir, and reschedule.
  4. Verify the client process owns and can write to data_dir/alloc.

Example fix

// before: data_dir spanning two mounts -> hard link fails across devices
# /etc/fstab
/dev/sdb1 /var/lib/nomad/alloc ... 
/dev/sdc1 /var/lib/nomad/alloc/1234 ... 
// after: single filesystem for data_dir
/dev/sdb1 /var/lib/nomad ...
Defensive patterns

Strategy: try-catch

Validate before calling

// client-side preflight
if st, err := os.Stat(sharedAllocDir); err != nil {
    return fmt.Errorf("shared alloc dir missing: %w", err)
} else if !st.IsDir() {
    return fmt.Errorf("%s is not a directory", sharedAllocDir)
}
// same-device check so hard links are possible
if !sameDevice(sharedAllocDir, sharedTaskDirParent) {
    return errors.New("alloc dir split across devices; hard links unavailable")
}

Try / catch

if err := td.Build(); err != nil {
    if strings.Contains(err.Error(), "Failed to mount shared directory") {
        log.Printf("task dir rebuild needed; consider stopping alloc and cleaning data_dir/alloc: %v", err)
    }
    return err
}

Prevention

When it happens

Trigger: fsi == fsisolation.Chroot, pathEmpty(pathExists check) showed the task SharedTaskDir absent or empty, and linkDir(t.SharedAllocDir, t.SharedTaskDir, false) returned an error (mkdir/link failure).

Common situations: Alloc directory removed or recreated externally while the allocation runs; permission problems after client user changes; filesystems (cross-device) where hard linking fails and copy fallback also fails; stale state from unclean shutdowns.

Related errors

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