hashicorp/nomad · error

invalid constraint: %v

Error message

invalid constraint: %v

What it means

Each constraint on a host volume must pass Constraint.Validate; failures are wrapped as 'invalid constraint: %v'. Additionally, distinct_hosts and distinct_property operands are rejected outright because host volumes of the same name are always placed on distinct hosts by construction.

Source

Thrown at nomad/structs/host_volumes.go:160

		mErr = multierror.Append(mErr, errors.New("missing name"))
	}

	if hv.RequestedCapacityMaxBytes < hv.RequestedCapacityMinBytes {
		mErr = multierror.Append(mErr, fmt.Errorf(
			"capacity_max (%d) must be larger than capacity_min (%d)",
			hv.RequestedCapacityMaxBytes, hv.RequestedCapacityMinBytes))
	}

	for _, cap := range hv.RequestedCapabilities {
		err := cap.Validate()
		if err != nil {
			mErr = multierror.Append(mErr, err)
		}
	}

	for _, constraint := range hv.Constraints {
		if err := constraint.Validate(); err != nil {
			mErr = multierror.Append(mErr, fmt.Errorf("invalid constraint: %v", err))
		}
		switch constraint.Operand {
		case ConstraintDistinctHosts, ConstraintDistinctProperty:
			mErr = multierror.Append(mErr, fmt.Errorf(
				"invalid constraint %s: host volumes of the same name are always on distinct hosts", constraint.Operand))
		default:
		}
	}

	return helper.FlattenMultierror(mErr.ErrorOrNil())
}

// ValidateUpdate verifies that an update to a volume is safe to make.
func (hv *HostVolume) ValidateUpdate(existing *HostVolume) error {
	if existing == nil {
		return nil
	}

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Remove distinct_hosts/distinct_property constraints from the volume
2. Fix the constraint fields (operand, LTarget, RTarget) so constraint.Validate() passes
3. Use supported operands only (e.g. attribute comparisons)

Example fix

// before
constraints { attribute = "${node.unique.id}"; operand = "distinct_hosts" }
// after
constraints { attribute = "${attr.kernel.name}"; operand = "="; value = "linux" }

for _, c := range hv.Constraints {
  if err := c.Validate(); err != nil { return err }
  if c.Operand == structs.ConstraintDistinctHosts || c.Operand == structs.ConstraintDistinctProperty {
    return fmt.Errorf("operand %s unsupported on host volumes", c.Operand)
  }
}

if err := hv.Validate(); err != nil {
  return fmt.Errorf("fix volume constraints: %w", err)
}

When it happens

Trigger: Registering a host volume with a malformed constraint (missing operand/target, bad LTarget/RTarget) or with operand distinct_hosts / distinct_property set.

Common situations: Copying job-level constraints onto host volumes without realizing some operands are unsupported there, typos in operand names, or incomplete constraint objects from API clients.

Related errors

• validating volume %q against state failed: %v
• volume validation failed: %w
• volume validation failed: no such namespace %q
• node ID %q is not in pool %q
• node %s is not feasible for volume

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