Consul Connect group %q with service %q must not contain upp

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.

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)

Solutions

Rename the task group to all lowercase (e.g. group "web").
Ensure any templated job/group names are lowercased before submission.
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 {} }
  }
}

Defensive patterns

Strategy: validation

Validate before calling

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`);
  }
}

Type guard

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

Prevention

Name all task groups in lowercase, especially those using connect.
Lowercase group names when generating jobs from templates or external sources.
Lint job HCL for uppercase group/service names in connect-enabled groups.

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

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