hashicorp/nomad · error

invalid name %q, must match regex %s

Error message

invalid name %q, must match regex %s

What it means

ValidateConsulClusterName validates Consul (and Vault) cluster names against ^[a-zA-Z0-9-_]{1,128}$. If the name contains other characters (dots, slashes, spaces, colons) or exceeds 128 characters, this error is returned. Cluster names must be simple identifiers so they can be safely used in configuration and state references.

Source

Thrown at nomad/structs/consul.go:100

	var clusterName string
	if c != nil && c.Cluster != "" {
		clusterName = c.Cluster
	} else {
		clusterName = ConsulDefaultCluster
	}

	return fmt.Sprintf("%s_%s", ConsulTaskIdentityNamePrefix, clusterName)
}

var (
	// validConsulVaultClusterName is the rule used to validate a Consul or
	// Vault cluster name.
	validConsulVaultClusterName = regexp.MustCompile("^[a-zA-Z0-9-_]{1,128}$")
)

func ValidateConsulClusterName(cluster string) error {
	if !validConsulVaultClusterName.MatchString(cluster) {
		return fmt.Errorf("invalid name %q, must match regex %s", cluster, validConsulVaultClusterName)
	}

	return nil
}

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Rename the cluster using only letters, digits, hyphens, and underscores (1-128 chars), e.g. "dc1-prod".
2. Move DNS names/addresses into the address field, not the cluster name.
3. Validate with the regex ^[a-zA-Z0-9-_]{1,128}$ before deploying config.

Example fix

// before
consul {
  name = "consul.prod.example.com"
}
// after
consul {
  name = "consul-prod"
  address = "consul.prod.example.com:8500"
}

var clusterNameRe = regexp.MustCompile(`^[a-zA-Z0-9-_]{1,128}$`)
if !clusterNameRe.MatchString(clusterName) {
  return fmt.Errorf("cluster name %q must match [a-zA-Z0-9-_]{1,128}", clusterName)
}

When it happens

Trigger: Configuring a Consul cluster (e.g. nomad consul blocks or agent config 'consul.cluster') with a name containing invalid characters like '.' or ':' or longer than 128 chars, via IsValidConfig during config validation.

Common situations: Naming clusters after FQDNs ('consul.prod.example.com'); including URL schemes or paths; pasting an address instead of a name into the cluster name field.

Related errors

• service %q contains invalid check: agent checks do not suppo
• invalid initial check state (%s), must be one of %q, %q, %q
• error creating bootstrap configuration for Connect proxy sid
• failed to parse config:
• only one of cgroups_v1_override and cgroups_v2_override may

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