non-default Consul cluster requires Nomad Enterprise

Error message

non-default Consul cluster requires Nomad Enterprise

What it means

In Nomad open source (CE), jobs may only use the default Consul cluster. The CE jobConsulHook's validateCluster returns this error when a job references any consul cluster name other than "default"; multi-cluster Consul is a Nomad Enterprise feature.

Source

Thrown at nomad/job_endpoint_hook_consul_ce.go:62

			if task.Consul != nil {
				err := h.validateTaskPartitionMatchesGroup(groupPartition, task.Consul)
				if err != nil {
					return nil, err
				}

				if err := h.validateCluster(task.Consul.Cluster); err != nil {
					return nil, err
				}
			}
		}
	}

	return nil, nil
}

func (h jobConsulHook) validateCluster(name string) error {
	if name != structs.ConsulDefaultCluster {
		return errors.New("non-default Consul cluster requires Nomad Enterprise")
	}
	return nil
}

// Mutate ensures that the job's Consul cluster has been configured to be the
// default Consul cluster if unset
func (h jobConsulHook) Mutate(job *structs.Job) (*structs.Job, []error, error) {
	return h.mutateImpl(job, structs.ConsulDefaultCluster), nil, nil
}

View on GitHub (pinned to 482b49bf1a)

Solutions

Remove the `cluster` field from the job's consul block so it defaults to "default".
Upgrade to Nomad Enterprise if multi-Consul-cluster is genuinely needed.
Point the agent's own consul configuration at the desired cluster instead of per-job overrides.

Example fix

// before
consul {
  cluster = "staging"
}

// after
consul {}

Defensive patterns

Strategy: validation

Validate before calling

if group.Consul != nil && group.Consul.Cluster != "" && group.Consul.Cluster != "default" {
  return errors.New("requires Nomad Enterprise")
}

Prevention

Omit consul.cluster on OSS clusters
Check edition/licensing before using multi-cluster features
Validate job specs against the target cluster edition

When it happens

Trigger: Setting `consul { cluster = "<name>" }` on a group (or job-level namespace cluster config) with a non-default value and validating/submitting the job on a CE binary.

Common situations: Copying an Enterprise job file to an OSS cluster; experimenting with multi-cluster consul config locally without the Enterprise license.

Related errors

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