hashicorp/nomad · error

no such consul cluster: %s

Error message

no such consul cluster: %s

What it means

prepareConsulTokensForTask resolves the Consul cluster name for the task (via task.GetConsulClusterName(tg), driven by the consul.cluster config on the group/task) and looks it up in the client's h.consulConfigs map. If the resolved cluster name has no corresponding client Consul configuration, this error is returned. It means the allocation references a Consul cluster the Nomad client does not know about.

Source

Thrown at client/allocrunner/consul_hook.go:143

	// write the tokens to hookResources
	if err := h.resourcesBackend.setConsulTokens(tokens); err != nil {
		h.logger.Error("unable to update tokens in state", "error", err)
	}

	return nil
}

func (h *consulHook) prepareConsulTokensForTask(task *structs.Task, tg *structs.TaskGroup, tokens map[string]map[string]*consulapi.ACLToken) error {
	if task == nil {
		// programming error
		return fmt.Errorf("cannot prepare consul tokens, no task specified")
	}

	clusterName := task.GetConsulClusterName(tg)
	consulConfig, ok := h.consulConfigs[clusterName]
	if !ok {
		return fmt.Errorf("no such consul cluster: %s", clusterName)
	}

	// Find task workload identity for Consul.
	widName := fmt.Sprintf("%s_%s", structs.ConsulTaskIdentityNamePrefix, consulConfig.Name)
	wid := task.GetIdentity(widName)
	if wid == nil {
		// Skip task if it doesn't have an identity for Consul since it doesn't
		// need a token.
		return nil
	}

	tokenName := widName + "/" + task.Name
	token := tokens[clusterName][tokenName]

	// If no token was previously stored, create one.
	if token == nil {
		// Find signed workload identity.
		ti := *task.IdentityHandle(wid)

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Verify the consul.cluster value in the job matches a cluster name configured in the client agent's consul blocks
2. Run nomad node status / inspect the client config to confirm which Consul clusters the client knows
3. Update the client agent configuration to define the missing Consul cluster, then restart the nomad agent
4. Redeploy the job to a client whose configuration includes that cluster

Example fix

// before (job HCL)
consul { cluster = "prod-east" }
// after (match client-configured cluster name)
consul { cluster = "default" }

clusterName := task.GetConsulClusterName(tg)
if _, ok := clientConsulConfigs[clusterName]; !ok {
    return fmt.Errorf("job references consul cluster %q not configured on client", clusterName)
}

if err := hook.Prerun(); err != nil {
    var missing *ConsulClusterError
    if strings.Contains(err.Error(), "no such consul cluster") {
        // reschedule after fixing client config
    }
}

When it happens

Trigger: A job sets consul.cluster (or the interpolated name resolves) to a cluster name absent from the agent's consul.blocks/consul configuration, then Prerun tries to derive a Consul workload-identity token for the task.

Common situations: Typo in the job's consul.cluster value; job written against a multi-cluster setup but the client agent lacks that cluster block; job submitted to clients running an older Nomad without Consul cluster support; client config changed/removed the cluster after the alloc was placed.

Related errors

• Failed to initialize Consul client: %v
• server_service_name must be set when auto_advertise is enabl
• client_service_name must be set when auto_advertise is enabl
• server_join and start_join cannot both be defined; prefer se
• error creating bootstrap configuration for Connect proxy sid

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