hashicorp/nomad · error

Service name must be valid per RFC 1123 and can contain only

Error message

Service name must be valid per RFC 1123 and can contain only alphanumeric characters or dashes and must be no longer than 63 characters

What it means

ValidateName enforces RFC 1123 DNS-label rules on service names: only alphanumeric characters and dashes, 1-63 characters, must start and end with an alphanumeric. This is stricter than Consul to keep names compatible with consul-template (which disallows dots) and other DNS-based consumers.

Source

Thrown at nomad/structs/services.go:954

		return fmt.Errorf("Service identity must provide at least one target aud value")
	}

	return nil
}

// ValidateName checks if the service Name is valid and should be called after
// the name has been interpolated
func (s *Service) ValidateName(name string) error {
	// Ensure the service name is valid per RFC-952 §1
	// (https://tools.ietf.org/html/rfc952), RFC-1123 §2.1
	// (https://tools.ietf.org/html/rfc1123), and RFC-2782
	// (https://tools.ietf.org/html/rfc2782).
	//  This validation is enforced on Nomad, but not on Consul, however if
	//  consul-template is being used, service names with dots in them wont be
	//  admissible.
	re := regexp.MustCompile(`^(?i:[a-z0-9]|[a-z0-9][a-z0-9\-]{0,61}[a-z0-9])$`)
	if !re.MatchString(name) {
		return fmt.Errorf("Service name must be valid per RFC 1123 and can contain only alphanumeric characters or dashes and must be no longer than 63 characters")
	}
	return nil
}

// LegacyAgentID is used only for generating the ID for services registered by a
// pre-FIPS-compatible Nomad agent, so that if the agent was not shutdown
// gracefully before upgrading, it can still deregister its old services.
//
// COMPAT: remove once upgrades from pre-FIPS-compatible agents are no longer
// supported. Upgrading agents in-place to FIPS-enabled is unsupported.
func (s *Service) LegacyAgentID(role string) string {
	if fips140.Enabled() {
		return ""
	}
	h := sha1.New()
	x := s.hashImpl(h, role, "", false)
	return fmt.Sprintf("_nomad-%s-%s", role, x)
}

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Rename the service to use only letters, digits, and dashes (e.g. "my-service").
2. Shorten the name to at most 63 characters.
3. Strip leading/trailing dashes and any dots/underscores from generated names.

Example fix

// before
service {
  name = "my_app.web"
}
// after
service {
  name = "my-app-web"
}

var rfc1123 = regexp.MustCompile(`^(?i:[a-z0-9]|[a-z0-9][a-z0-9\-]{0,61}[a-z0-9])$`)
func validServiceName(name string) bool { return rfc1123.MatchString(name) }

func isValidServiceName(name string) bool {
  if len(name) == 0 || len(name) > 63 { return false }
  for i, r := range name {
    ok := (r >= 'a' && r <= 'z') || (r >= 'A' && r <= 'Z') || (r >= '0' && r <= '9') || r == '-'
    if !ok || ((i == 0 || i == len(name)-1) && r == '-') { return false }
  }
  return true
}

When it happens

Trigger: Naming a service "my_service" (underscore), "MyService" is fine per (?i) but "my.service", "-web", "web-", or a name longer than 63 chars.

Common situations: Using app names with underscores or dots in service stanzas; very long names from generated configs; copying Kubernetes-style names containing dots.

Related errors

• Missing task name
• Task cannot be named "alloc"
• Task name cannot include slashes
• Task name cannot include null characters
• "%s" contains characters %s that require the 'index' functio

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