hashicorp/nomad · error

validating volume %q against state failed: %v

Error message

validating volume %q against state failed: %v

What it means

During HostVolume.Create, before placing the volume the endpoint runs validateVolumeForState, which checks that every referenced namespace, node, and node pool actually exists in the current state snapshot. Any failure is wrapped as "validating volume %q against state failed". The create is rejected so that no dangling references are persisted.

Source

Thrown at nomad/host_volume_endpoint.go:248

	// ensure we only try to create a valid volume or make valid updates to a
	// volume
	snap, err := v.srv.State().Snapshot()
	if err != nil {
		return err
	}
	existing, err := v.validateVolumeUpdate(vol, snap)
	if err != nil {
		return err
	}

	// set zero values as needed, possibly from existing
	now := time.Now()
	vol.CanonicalizeForCreate(existing, now)

	// make sure any namespaces, nodes, or pools actually exist
	err = v.validateVolumeForState(vol, snap)
	if err != nil {
		return fmt.Errorf("validating volume %q against state failed: %v", vol.Name, err)
	}

	_, err = v.placeHostVolume(snap, vol)
	if err != nil {
		return fmt.Errorf("could not place volume %q: %w", vol.Name, err)
	}

	warn, err := v.enforceEnterprisePolicy(
		snap, vol, args.GetIdentity().GetACLToken(), args.PolicyOverride)
	if warn != nil {
		reply.Warnings = warn.Error()
	}
	if err != nil {
		return err
	}

	// serialize client RPC and raft write per volume ID
	index, err := v.serializeCall(vol.ID, "create", func() (uint64, error) {

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Read the wrapped inner error — it names the missing namespace, node, or node pool.
2. Verify the referenced node exists: `nomad node status`; use a live node's ID, not a hostname, unless the field expects one.
3. Verify the node pool exists: `nomad node pool list`, and create it if needed.
4. Verify the namespace exists: `nomad namespace list`; pass -namespace explicitly so it is not defaulted incorrectly.
5. Re-run the create with corrected references.

Example fix

# before: node pool 'prod' does not exist
nomad host volume create -name web-vol -node-id <id> -node-pool prod ...
// after: create/verify pool first, then reference it
nomad node pool create -name prod
nomad host volume create -name web-vol -node-id <id> -node-pool prod ...

// verify referenced entities exist before creating the volume
if _, _, err := client.Nodes().Info(vol.NodeID, nil); err != nil {
    return fmt.Errorf("node %s not found", vol.NodeID)
}
if _, err := client.NodePools().Info(vol.NodePool, nil); err != nil {
    return fmt.Errorf("node pool %s not found", vol.NodePool)
}
if _, _, err := client.Namespaces().Info(vol.Namespace, nil); err != nil {
    return fmt.Errorf("namespace %s not found", vol.Namespace)
}

func refsExist(client *nomad.Client, vol *api.HostVolume) error {
    if _, _, err := client.Nodes().Info(vol.NodeID, nil); err != nil { return err }
    if vol.NodePool != "" {
        if _, err := client.NodePools().Info(vol.NodePool, nil); err != nil { return err }
    }
    return nil
}

_, err := client.HostVolumes().Create(req, nil)
if err != nil && strings.Contains(err.Error(), "validating volume") {
    // parse wrapped cause: missing namespace/node/pool; fix spec and retry
}

When it happens

Trigger: Creating a dynamic host volume whose spec references a non-existent namespace, node ID, or node pool; validateVolumeForState returns an error which is wrapped with the volume name.

Common situations: Typo'd node ID or node pool name in the volume spec, volume targeted at a node that was drained/removed, creating volumes in a namespace that has not been created yet, or multi-namespace requests against the wrong namespace name.

Related errors

• job_submission requires a namespace
• job_submission requires a jobID
• could not place volume %q: %w
• volume validation failed: %w
• volume validation failed: no such namespace %q

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