{"record":{"id":"04b75ab2dfaaef3d","repo":"hashicorp/nomad","slug":"failed-to-add-check-q-v","errorCode":null,"errorMessage":"failed to add check %q: %v","messagePattern":"failed to add check %q: (.+?)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"command/agent/consul/service_client.go","lineNumber":1279,"sourceCode":"\t\t\t\treturn fmt.Errorf(\"service %q contains invalid check: agent checks do not support scripts\", service.Name)\n\t\t\t}\n\t\t\tcheckHost, checkPort := serviceReg.Address, serviceReg.Port\n\t\t\tif check.PortLabel != \"\" {\n\t\t\t\t// Unlike tasks, agents don't use port labels. Agent ports are\n\t\t\t\t// stored directly in the PortLabel.\n\t\t\t\thost, rawport, err := net.SplitHostPort(check.PortLabel)\n\t\t\t\tif err != nil {\n\t\t\t\t\treturn fmt.Errorf(\"error parsing port label %q from check %q: %v\", service.PortLabel, check.Name, err)\n\t\t\t\t}\n\t\t\t\tport, err := strconv.Atoi(rawport)\n\t\t\t\tif err != nil {\n\t\t\t\t\treturn fmt.Errorf(\"error parsing port %q from check %q: %v\", rawport, check.Name, err)\n\t\t\t\t}\n\t\t\t\tcheckHost, checkPort = host, port\n\t\t\t}\n\t\t\tcheckReg, err := createCheckReg(id, checkID, check, checkHost, checkPort, \"\")\n\t\t\tif err != nil {\n\t\t\t\treturn fmt.Errorf(\"failed to add check %q: %v\", check.Name, err)\n\t\t\t}\n\t\t\tops.regChecks = append(ops.regChecks, checkReg)\n\t\t}\n\t}\n\n\t// Don't bother committing agent checks if we're already shutting down\n\tc.agentLock.Lock()\n\tdefer c.agentLock.Unlock()\n\tselect {\n\tcase <-c.shutdownCh:\n\t\treturn nil\n\tdefault:\n\t}\n\n\t// Now add them to the registration queue\n\tc.commit(&ops)\n\n\t// Record IDs for deregistering on shutdown","sourceCodeStart":1261,"sourceCodeEnd":1297,"githubUrl":"https://github.com/hashicorp/nomad/blob/482b49bf1aec006f089bcfc7e632d8f6ac303e5e/command/agent/consul/service_client.go#L1261-L1297","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Read the wrapped %v detail from createCheckReg and correct the offending check field (most often address_mode or unsupported check options)","Remove unsupported options (expose, driver address modes) from agent checks","Simplify the check to a minimal http/tcp check and re-add options one at a time","Compare the check against task-service checks known to work to spot the invalid field"],"exampleFix":"// before\ncheck {\n  type = \"http\"\n  address_mode = \"driver\"\n  port_label = \"127.0.0.1:4646\"\n}\n// after\ncheck {\n  type = \"http\"\n  port_label = \"127.0.0.1:4646\"\n}","handlingStrategy":"validation","validationCode":"// Keep agent checks minimal: type + host:port + path/interval\nif check.AddressMode != \"\" && check.AddressMode != \"host\" {\n  return fmt.Errorf(\"agent check %q: unsupported address_mode %q\", check.Name, check.AddressMode)\n}","typeGuard":null,"tryCatchPattern":"if err := client.RegisterAgentWorkload(w); err != nil {\n  if strings.Contains(err.Error(), \"failed to add check\") {\n    // log wrapped cause, drop offending check, retry registration\n  }\n}","preventionTips":["Keep agent checks to plain http/tcp definitions","Don't reuse task-service check blocks verbatim for agents","Read the wrapped createCheckReg error for the exact invalid field","Pin check options to what your Consul agent version supports"],"tags":["consul","nomad","check-registration"],"backgroundTag":"check-registration-failed","analyzedSha":"482b49bf1aec006f089bcfc7e632d8f6ac303e5e","analyzedAt":"2026-09-04T07:54:14.808Z","contentChangedAt":"2026-09-04T07:54:14.808Z","schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}