{"record":{"id":"0982f91760107384","repo":"hashicorp/nomad","slug":"reserved-port-collision-s-d","errorCode":null,"errorMessage":"reserved port collision %s=%d","messagePattern":"reserved port collision (.+?)=(.+?)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"nomad/structs/network.go","lineNumber":494,"sourceCode":"\n\tfor _, port := range ask.ReservedPorts {\n\t\treservedIdx[port.HostNetwork] = append(reservedIdx[port.HostNetwork], port)\n\n\t\t// allocPort is set in the inner for loop if a port mapping can be created\n\t\t// if allocPort is still nil after the loop, the port wasn't available for reservation\n\t\tvar allocPort *AllocatedPortMapping\n\t\tvar addrErr error\n\t\tfor _, addr := range idx.HostNetworks[port.HostNetwork] {\n\t\t\t// Guard against invalid port\n\t\t\tif port.Value < 0 || port.Value >= MaxValidPort {\n\t\t\t\treturn nil, fmt.Errorf(\"invalid port %d (out of range)\", port.Value)\n\t\t\t}\n\n\t\t\t// Check if in use\n\t\t\tif !port.IgnoreCollision {\n\t\t\t\tused := idx.getUsedPortsFor(addr.Address)\n\t\t\t\tif used != nil && used.Check(uint(port.Value)) {\n\t\t\t\t\taddrErr = fmt.Errorf(\"reserved port collision %s=%d\", port.Label, port.Value)\n\t\t\t\t\tcontinue\n\t\t\t\t}\n\t\t\t}\n\n\t\t\tallocPort = &AllocatedPortMapping{\n\t\t\t\tLabel:           port.Label,\n\t\t\t\tValue:           port.Value,\n\t\t\t\tTo:              port.To,\n\t\t\t\tHostIP:          addr.Address,\n\t\t\t\tIgnoreCollision: port.IgnoreCollision,\n\t\t\t}\n\t\t\tbreak\n\t\t}\n\n\t\tif allocPort == nil {\n\t\t\tif addrErr != nil {\n\t\t\t\treturn nil, addrErr\n\t\t\t}","sourceCodeStart":476,"sourceCodeEnd":512,"githubUrl":"https://github.com/hashicorp/nomad/blob/482b49bf1aec006f089bcfc7e632d8f6ac303e5e/nomad/structs/network.go#L476-L512","documentation":"AssignPorts could not allocate a requested reserved port because that port on the candidate host address is already reserved by another allocation on the same node. Nomad tracks used ports per IP via a bitset (getUsedPortsFor); when a requested static port collides and the port is not marked IgnoreCollision, the address is skipped and this error is returned. It indicates host port contention on a particular network interface.","triggerScenarios":"Calling NetworkIndex.AssignPorts with a NetworkResource whose ReservedPorts (or HostNetwork-reserved ports) include a port number already in the index's used set for that address; the port's IgnoreCollision flag is false.","commonSituations":"Two jobs on the same node request static port 8080; a service hardcodes well-known ports (80, 443) that the host already uses; re-scheduling after a stale allocation still holds the port in the index.","solutions":["Change the task's static reserved port to a free value or switch to a dynamic port (omit Value / use a port range).","Move the task to a host_network with fewer allocations so the port is free on that interface.","Set IgnoreCollision: true on the port if co-existence is safe in your environment.","Spread static-port workloads across client nodes to reduce per-node contention."],"exampleFix":"// before\nReservedPorts: [{Label: \"http\", Value: 8080}]\n// after\nReservedPorts: [{Label: \"http\", Static: 0, To: 8080}] // dynamic host port mapped to container 8080","handlingStrategy":"validation","validationCode":"// before submitting a job with static ports, check they're free on the target host\nfunc validateStaticPortsFree(ports []int, host string) error {\n  for _, p := range ports {\n    if p < 1 || p > 65535 { return fmt.Errorf(\"port %d out of range\", p) }\n    ln, err := net.Listen(\"tcp\", fmt.Sprintf(\"%s:%d\", host, p))\n    if err != nil { return fmt.Errorf(\"port %d in use\", p) }\n    ln.Close()\n  }\n  return nil\n}","typeGuard":"func isValidPort(p int) bool { return p > 0 && p < 65536 }","tryCatchPattern":"null","preventionTips":["Prefer dynamic ports unless a well-known port is genuinely required","Keep a registry of static ports per node to avoid duplicate pins","Use distinct host_networks for workloads needing the same static port"],"tags":["nomad","port-collision","network","scheduling"],"backgroundTag":"port-already-in-use","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"}