hashicorp/nomad · error

Invalid host volume name: %#v

Error message

Invalid host volume name: %#v

What it means

Nomad's acl.Parse() (acl/policy.go:643) validates every host_volume block's name against the regex ^[a-zA-Z0-9-*]{1,128}$ before compiling the ACL. If the name is empty, longer than 128 chars, or contains characters outside alphanumerics, hyphen, asterisk (e.g. '/', '_', ':' or whitespace), parsing fails and the whole policy is rejected. The offending HostVolumePolicy struct is printed with %#v to identify the bad block.

Source

Thrown at acl/policy.go:644

		}
		for _, cap := range np.Capabilities {
			if !isNodePoolCapabilityValid(cap) {
				return nil, fmt.Errorf("Invalid node pool capability '%s' for '%s'", cap, np.Name)
			}
		}

		if np.Policy != "" {
			extraCap := expandNodePoolPolicy(np.Policy)
			np.Capabilities = append(np.Capabilities, extraCap...)
		}

		// Remove the node-pool name from the extra key list.
		p.removeExtraKey(np.Name)
	}

	for _, hv := range p.HostVolumes {
		if !validVolume.MatchString(hv.Name) {
			return nil, fmt.Errorf("Invalid host volume name: %#v", hv)
		}
		if hv.Policy != "" && !isPolicyValid(hv.Policy) {
			return nil, fmt.Errorf("Invalid host volume policy: %#v", hv)
		}
		for _, cap := range hv.Capabilities {
			if !isHostVolumeCapabilityValid(cap) {
				return nil, fmt.Errorf("Invalid host volume capability '%s': %#v", cap, hv)
			}
		}

		// Expand the short hand policy to the capabilities and
		// add to any existing capabilities
		if hv.Policy != "" {
			extraCap := expandHostVolumePolicy(hv.Policy)
			hv.Capabilities = append(hv.Capabilities, extraCap...)
		}

		// Remove the host-volume name from the extra key list.

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Rename the host_volume block key so it only contains letters, digits, hyphens, or asterisks and is 1-128 characters long (e.g. host_volume "web-data" { ... }).
2. If the name was templated, verify the substituted variable is non-empty and contains no '/', '_', or whitespace before generating the policy.
3. Check the printed %#v struct in the error to see which host_volume block has the bad Name and fix just that one.

Example fix

// before
host_volume "data/vol1" {
  policy = "read"
}
// after
host_volume "data-vol1" {
  policy = "read"
}

var validVolume = regexp.MustCompile(`^[a-zA-Z0-9-*]{1,128}$`)
for _, hv := range policy.HostVolumes {
    if !validVolume.MatchString(hv.Name) {
        return fmt.Errorf("host volume %q must match [a-zA-Z0-9-*]{1,128}", hv.Name)
    }
}

func isValidHostVolumeName(name string) bool {
    return regexp.MustCompile(`^[a-zA-Z0-9-*]{1,128}$`).MatchString(name)
}

_, err := acl.Parse(rules, acl.PolicyParseStrict)
if err != nil {
    if strings.Contains(err.Error(), "Invalid host volume name") {
        // surface which volume name failed and fix the HCL
    }
    return err
}

When it happens

Trigger: Calling acl.Parse(rules, strict) (or the Nomad API 'PUT /v1/acl/policy' endpoint) where the HCL/JSON policy contains a host_volume block whose key (the volume name) does not match validVolume: empty name, name with '/' or '_' or spaces, or a name exceeding 128 characters.

Common situations: Typing a volume name copied from a job spec that uses underscores or slashes (e.g. 'web_data' or 'data/vol1'); forgetting the volume name entirely ('host_volume { ... }'); scripting policy generation that substitutes an empty or multiline variable into the name.

Related errors

• Invalid host volume policy: %#v
• Invalid namespace name: %#v
• Invalid namespace policy: %#v
• Invalid namespace capability '%s': %#v
• Invalid variable policy: no variable paths in namespace %s

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