hashicorp/nomad · error

Consul Connect group

Error message

Consul Connect group %q with service %q must not contain uppercase characters

What it means

Same lowercase invariant as the service name, applied to the task group name: a connect group whose group name contains uppercase characters is rejected, because Consul derives the proxy ID from group and service names and assumes lowercase.

Solutions

1. Rename the task group to all lowercase (e.g. group "web").
2. Ensure any templated job/group names are lowercased before submission.
3. If the service has no connect block, remove it to bypass this validation.

Example fix

// before
group "WebApp" {
  service {
    name = "web"
    connect { sidecar_service {} }
  }
}
// after
group "webapp" {
  service {
    name = "web"
    connect { sidecar_service {} }
  }
}

function validateConnectGroupName(group) {
  const hasConnect = (group.services || []).some(s => s.connect);
  if (hasConnect && group.name !== group.name.toLowerCase()) {
    throw new Error(`connect group name "${group.name}" must be lowercase`);
  }
}

function isLowercase(s) { return typeof s === 'string' && s === s.toLowerCase(); }

When it happens

Trigger: Submitting a job where a task group containing a connect sidecar service is named with any uppercase letters, e.g. `group "Web"` with a connect service, in groupConnectSidecarValidate.

Common situations: Group names mirroring capitalized app or team names; templating that injects job/group names from uppercase sources; users converting legacy jobs with capitalized group names to use connect.

Related errors

• Consul Connect service name
• ErrConnectInvalidNetworkMode
• ErrConnectRequireOneNetwork
• exposed service check
• exposed service check

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

Appendix: source

Thrown at nomad/job_endpoint_hook_connect.go:668

	return fmt.Errorf("%s: %w: group %q uses network mode %q; must be %s",
		errorPrefix, ErrConnectInvalidNetworkMode, g.Name, mode, allowed)
}

func groupConnectSidecarValidate(g *structs.TaskGroup, s *structs.Service) error {
	if err := groupConnectNetworkModeValidate(g, "connect sidecar", false); err != nil {
		return err
	}

	// We must enforce lowercase characters on group and service names for connect
	// sidecar proxies, because Consul assumes this invariant without validating it.
	// https://github.com/hashicorp/consul/blob/v1.9.5/command/connect/proxy/proxy.go#L235

	if s.Name != strings.ToLower(s.Name) {
		return fmt.Errorf("Consul Connect service name %q in group %q must not contain uppercase characters", s.Name, g.Name)
	}

	if g.Name != strings.ToLower(g.Name) {
		return fmt.Errorf("Consul Connect group %q with service %q must not contain uppercase characters", g.Name, s.Name)
	}

	return nil
}

func groupConnectNativeValidate(g *structs.TaskGroup, s *structs.Service) error {
	// note that network mode is not enforced for connect native services

	if _, err := getNamedTaskForNativeService(g, s.Name, s.TaskName); err != nil {
		return err
	}
	return nil
}

func groupConnectGatewayValidate(g *structs.TaskGroup) error {
	// note that gateways can run in host network mode
	return groupConnectNetworkModeValidate(g, "connect gateway", true)
}

View on GitHub (pinned to 482b49bf1a)