hashicorp/nomad · error

unknown service registration provider: %q

Error message

unknown service registration provider: %q

What it means

The service registration wrapper dispatches RegisterWorkload to the registered backend (Nomad or Consul) based on the workload's provider string. If the provider is neither "nomad" nor "consul", the wrapper returns this error because no handler exists for it.

Source

Thrown at client/serviceregistration/wrapper/wrapper.go:63

// function. It determines which backend provider to call and passes the
// workload unless the provider is unknown, in which case an error will be
// returned.
func (h *HandlerWrapper) RegisterWorkload(workload *serviceregistration.WorkloadServices) error {

	// Don't rely on callers to check there are no services to register.
	if len(workload.Services) == 0 {
		return nil
	}

	provider := workload.RegistrationProvider()

	switch provider {
	case structs.ServiceProviderNomad:
		return h.nomadServiceProvider.RegisterWorkload(workload)
	case structs.ServiceProviderConsul:
		return h.consulServiceProvider.RegisterWorkload(workload)
	default:
		return fmt.Errorf("unknown service registration provider: %q", provider)
	}
}

// RemoveWorkload wraps the serviceregistration.Handler RemoveWorkload
// function. It determines which backend provider to call and passes the
// workload unless the provider is unknown.
func (h *HandlerWrapper) RemoveWorkload(services *serviceregistration.WorkloadServices) {

	var provider string

	// It is possible the services field is empty depending on the exact
	// situation which resulted in the call.
	if len(services.Services) > 0 {
		provider = services.RegistrationProvider()
	}

	// Call the correct provider, if we have managed to identify it. An empty
	// string means you didn't find a provider, therefore default to consul.

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Set provider to "nomad" or "consul" explicitly in each service stanza
2. Remove invalid/empty provider fields so defaults apply and validation passes
3. Ensure client binary version supports the provider used in the job (upgrade Nomad if needed)
4. Run nomad job validate before submission to catch unknown provider values

Example fix

// before
service {
  name = "web"
  provider = "consul-nomad"
}
// after
service {
  name = "web"
  provider = "consul"
}

switch provider {
case "nomad", "consul":
    // ok
default:
    return fmt.Errorf("refusing to register: unsupported provider %q", provider)
}

func knownProvider(p string) bool {
    return p == structs.ServiceProviderNomad || p == structs.ServiceProviderConsul
}

err := wrapper.RegisterWorkload(workload)
if err != nil && strings.HasPrefix(err.Error(), "unknown service registration provider") {
    logger.Error("bad provider in workload registration", "provider", workload.Provider)
    return err
}

When it happens

Trigger: A service stanza (or code path building WorkloadRegistrations) carries a provider value other than structs.ServiceProviderNomad or structs.ServiceProviderConsul into wrapper.RegisterWorkload — e.g. from a hand-crafted job, an API submission bypassing validation, or stale/foreign data.

Common situations: Job spec sets provider = "consul-nomad" or similar typo; job created for a newer Nomad that supports a provider the running client does not know; tooling generating registrations with empty/garbage provider fields.

Related errors

• invalid address mode %q
• unknown service registration provider for update: %q
• service registration not found
• secret provider cannot be empty
• cannot use address_mode="alloc": no allocation network statu

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