{"record":{"id":"17e0f742f86c93ce","repo":"hashicorp/nomad","slug":"check-q-has-invalid-numeric-port-d","errorCode":null,"errorMessage":"check %q has invalid numeric port %d","messagePattern":"check %q has invalid numeric port (.+?)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"nomad/structs/structs.go","lineNumber":8559,"sourceCode":"\t\t\t\t// Inherits from service\n\t\t\t\teffectivePort = service.PortLabel\n\t\t\t}\n\n\t\t\tif effectivePort == \"\" {\n\t\t\t\tmErr.Errors = append(mErr.Errors, fmt.Errorf(\"check %q is missing a port\", check.Name))\n\t\t\t\tcontinue\n\t\t\t}\n\n\t\t\tisNumeric := false\n\t\t\tportNumber, err := strconv.Atoi(effectivePort)\n\t\t\tif err == nil {\n\t\t\t\tisNumeric = true\n\t\t\t}\n\n\t\t\t// Numeric ports are fine for address_mode = \"driver\"\n\t\t\tif check.AddressMode == \"driver\" && isNumeric {\n\t\t\t\tif portNumber <= 0 {\n\t\t\t\t\tmErr.Errors = append(mErr.Errors, fmt.Errorf(\"check %q has invalid numeric port %d\", check.Name, portNumber))\n\t\t\t\t}\n\t\t\t\tcontinue\n\t\t\t}\n\n\t\t\tif isNumeric {\n\t\t\t\tmErr.Errors = append(mErr.Errors, fmt.Errorf(`check %q cannot use a numeric port %d without setting address_mode=\"driver\"`, check.Name, portNumber))\n\t\t\t\tcontinue\n\t\t\t}\n\n\t\t\t// PortLabel must exist, report errors by its parent service\n\t\t\taddServicePort(effectivePort, service.Name)\n\t\t}\n\t}\n\n\t// Get the set of group port labels.\n\tportLabels := make(map[string]struct{})\n\tif len(tgNetworks) > 0 {\n\t\tports := tgNetworks[0].PortLabels()","sourceCodeStart":8541,"sourceCodeEnd":8577,"githubUrl":"https://github.com/hashicorp/nomad/blob/482b49bf1aec006f089bcfc7e632d8f6ac303e5e/nomad/structs/structs.go#L8541-L8577","documentation":"When a check's effective port parses as a number and the check uses address_mode=\"driver\", Nomad validates that the numeric port is a positive TCP/UDP port. A value <= 0 fails this range check and produces this error naming the check and the offending number.","triggerScenarios":"Submitting a job where a check with address_mode=\"driver\" has a numeric port (via check port or inherited service port) that is zero or negative, e.g. port = \"0\" or a negative literal.","commonSituations":"Placeholder port 0 left in generated jobs; arithmetic/templating producing 0 or -1; mistyping a port when bypassing named labels under driver mode.","solutions":["Set the numeric port to a value between 1 and 65535.","Replace the numeric literal with a named network port label (preferred).","If port 0 was intentional dynamic assignment, use a group network `dynamic` port and reference its label instead."],"exampleFix":"// before\ncheck { name = \"tcp\"; type = \"tcp\"; address_mode = \"driver\"; port = \"0\" }\n\n// after\ncheck { name = \"tcp\"; type = \"tcp\"; address_mode = \"driver\"; port = \"8080\" }","handlingStrategy":"validation","validationCode":"n, err := strconv.Atoi(checkPort)\nif err == nil && n <= 0 {\n  return fmt.Errorf(\"check %q: numeric port %d must be > 0\", c.Name, n)\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Never use 0 or negative placeholders for check ports","Prefer named port labels over raw numeric ports","Range-check generated port values (1-65535) in job templating"],"tags":["nomad","health-check","port","validation"],"backgroundTag":"invalid-port-number","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"}