hashicorp/nomad · error

could not verify host path for %q: %w

Error message

could not verify host path for %q: %w

What it means

Returned by the host volume manager's Register when os.Stat on req.HostPath fails, meaning the path claimed for the volume does not exist or is not accessible on the client node. The manager releases the volume's lock, logs 'error registering volume', and wraps the stat error. Registration is aborted.

Source

Thrown at client/hostvolumemanager/host_volumes.go:167

	return resp, nil
}

// Register saves the request to state, and updates the node with the volume.
func (hvm *HostVolumeManager) Register(ctx context.Context,
	req *cstructs.ClientHostVolumeRegisterRequest) error {

	log := hvm.log.With("volume_name", req.Name, "volume_id", req.ID)

	// can't have two of the same volume name w/ different IDs per client node
	if _, err := hvm.locker.lock(req.Name, req.ID); err != nil {
		log.Error("duplicate volume name", "error", err)
		return err
	}

	_, err := os.Stat(req.HostPath)
	if err != nil {
		hvm.locker.release(req.Name)
		err = fmt.Errorf("could not verify host path for %q: %w", req.Name, err)
		log.Error("error registering volume", "error", err)
		return err
	}

	// generate a stub create request and plugin response for the fingerprint
	// and client state
	creq := &cstructs.ClientHostVolumeCreateRequest{
		ID:         req.ID,
		Name:       req.Name,
		NodeID:     req.NodeID,
		Parameters: req.Parameters,
	}
	volState := &cstructs.HostVolumeState{
		ID:        req.ID,
		CreateReq: creq,
		HostPath:  req.HostPath,
	}
	if err := hvm.stateMgr.PutDynamicHostVolume(volState); err != nil {

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Verify the path exists on the specific client node: run stat <path> as the nomad user
2. Create the directory (mkdir -p) and give the nomad user ownership/read access
3. Fix the host_path value in the volume specification
4. If path is node-specific, use a per-node volume or constraint so registration targets the right node
5. Recreate any mount/bind-mount that disappeared after reboot

Example fix

// before
volume "web" { type = "host" host_path = "/srv/data" }  # /srv/data missing
// after
$ sudo mkdir -p /srv/data && sudo chown nomad:nomad /srv/data
volume "web" { type = "host" host_path = "/srv/data" }

func ensureHostPath(p string) error {
    fi, err := os.Stat(p)
    if err != nil { return err }
    if !fi.IsDir() { return fmt.Errorf("%s is not a directory", p) }
    if _, err := os.Stat(filepath.Join(p, ".")); err != nil {
        return fmt.Errorf("no traverse permission on %s: %w", p, err)
    }
    return nil
}
// call before nomad volume register: ensureHostPath(req.HostPath)

func pathAccessible(p string) bool { _, err := os.Stat(p); return err == nil }

err := hvm.Register(req)
if err != nil {
    var perr *fs.PathError
    if errors.As(err, &perr) {
        log.Error("host path missing on this node", "path", perr.Path, "err", perr)
        // create the dir or fix the spec before retrying
    }
    return err
}

When it happens

Trigger: Calling Register (via nomad volume register / client host-volume API) with a HostPath that does not exist, was removed, or is not readable by the nomad agent user (including permission on any parent directory).

Common situations: Typo in host_path in the volume spec; directory deleted or never created on the client; path exists only on other nodes; bind mount not yet mounted; nomad user lacks traverse permissions; client restarted after host reboot losing the path.

Related errors

• ErrPluginNotExists
• alloc dir must be absolute
• error creating directory: %w
• error setting directory permission mode: %w
• error changing owner/group: %w

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