hashicorp/nomad · error

failed to add check %q: %v

Error message

failed to add check %q: %v

What it means

This wraps any failure from createCheckReg while converting a Nomad check into a Consul api.AgentCheck registration during agent service registration. createCheckReg validates check fields (e.g. unsupported fields like expose/grpc checks, address mode incompatibilities), so a check that cannot be represented for the agent is rejected and the whole service registration fails.

Source

Thrown at command/agent/consul/service_client.go:1279

				return fmt.Errorf("service %q contains invalid check: agent checks do not support scripts", service.Name)
			}
			checkHost, checkPort := serviceReg.Address, serviceReg.Port
			if check.PortLabel != "" {
				// Unlike tasks, agents don't use port labels. Agent ports are
				// stored directly in the PortLabel.
				host, rawport, err := net.SplitHostPort(check.PortLabel)
				if err != nil {
					return fmt.Errorf("error parsing port label %q from check %q: %v", service.PortLabel, check.Name, err)
				}
				port, err := strconv.Atoi(rawport)
				if err != nil {
					return fmt.Errorf("error parsing port %q from check %q: %v", rawport, check.Name, err)
				}
				checkHost, checkPort = host, port
			}
			checkReg, err := createCheckReg(id, checkID, check, checkHost, checkPort, "")
			if err != nil {
				return fmt.Errorf("failed to add check %q: %v", check.Name, err)
			}
			ops.regChecks = append(ops.regChecks, checkReg)
		}
	}

	// Don't bother committing agent checks if we're already shutting down
	c.agentLock.Lock()
	defer c.agentLock.Unlock()
	select {
	case <-c.shutdownCh:
		return nil
	default:
	}

	// Now add them to the registration queue
	c.commit(&ops)

	// Record IDs for deregistering on shutdown

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Read the wrapped %v detail from createCheckReg and correct the offending check field (most often address_mode or unsupported check options)
2. Remove unsupported options (expose, driver address modes) from agent checks
3. Simplify the check to a minimal http/tcp check and re-add options one at a time
4. Compare the check against task-service checks known to work to spot the invalid field

Example fix

// before
check {
  type = "http"
  address_mode = "driver"
  port_label = "127.0.0.1:4646"
}
// after
check {
  type = "http"
  port_label = "127.0.0.1:4646"
}

// Keep agent checks minimal: type + host:port + path/interval
if check.AddressMode != "" && check.AddressMode != "host" {
  return fmt.Errorf("agent check %q: unsupported address_mode %q", check.Name, check.AddressMode)
}

if err := client.RegisterAgentWorkload(w); err != nil {
  if strings.Contains(err.Error(), "failed to add check") {
    // log wrapped cause, drop offending check, retry registration
  }
}

When it happens

Trigger: RegisterAgentWorkload loop reaches createCheckReg(id, checkID, check, checkHost, checkPort, "") and the check struct contains fields invalid for a Consul registration (invalid address_mode, bad gRPC/expose settings, invalid check definition) causing createCheckReg to return an error.

Common situations: Misconfigured check block (e.g. address_mode set to 'driver' or 'alloc' which is meaningless for agents); grpc/expose options unsupported by the target; invalid method/header combination.

Related errors

• error creating bootstrap configuration for Connect proxy sid
• client stopped and may not longer create config entries
• non-default Consul cluster requires Nomad Enterprise
• expose may only be set for Consul service checks
• on_update may only be set to ignore_warnings for Consul serv

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