{"record":{"id":"92d4bb21c7f2e7bd","repo":"hashicorp/nomad","slug":"port-map-cannot-map-group-network-ports-use-po","errorCode":null,"errorMessage":"'port_map' cannot map group network ports, use 'ports' instead","messagePattern":"'port_map' cannot map group network ports, use 'ports' instead","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"drivers/docker/driver.go","lineNumber":1450,"sourceCode":"\t\t\t} else {\n\t\t\t\treturn c, fmt.Errorf(\"Port %q not found, check network block\", port)\n\t\t\t}\n\t\t}\n\tcase len(task.Resources.NomadResources.Networks) > 0:\n\t\tnetwork := task.Resources.NomadResources.Networks[0]\n\n\t\tfor _, port := range network.ReservedPorts {\n\t\t\tports.addMapped(port.Label, network.IP, port.Value, driverConfig.PortMap)\n\t\t}\n\n\t\tfor _, port := range network.DynamicPorts {\n\t\t\tports.addMapped(port.Label, network.IP, port.Value, driverConfig.PortMap)\n\t\t}\n\n\tdefault:\n\t\tif len(driverConfig.PortMap) > 0 {\n\t\t\tif task.Resources.Ports != nil {\n\t\t\t\treturn c, fmt.Errorf(\"'port_map' cannot map group network ports, use 'ports' instead\")\n\t\t\t}\n\t\t\treturn c, fmt.Errorf(\"Trying to map ports but no network interface is available\")\n\t\t}\n\t}\n\thostConfig.PortBindings = make(networkapi.PortMap, len(ports.publishedPorts))\n\tfor port, bindings := range ports.publishedPorts {\n\t\tparsedPort := networkapi.MustParsePort(string(port))\n\t\tconvertedBindings := make([]networkapi.PortBinding, len(bindings))\n\t\tfor i, binding := range bindings {\n\t\t\tconvertedBinding := networkapi.PortBinding{\n\t\t\t\tHostPort: binding.HostPort,\n\t\t\t}\n\t\t\tif binding.HostIP != \"\" {\n\t\t\t\tconvertedBinding.HostIP = netip.MustParseAddr(binding.HostIP)\n\t\t\t}\n\t\t\tconvertedBindings[i] = convertedBinding\n\t\t}\n\t\thostConfig.PortBindings[parsedPort] = convertedBindings","sourceCodeStart":1432,"sourceCodeEnd":1468,"githubUrl":"https://github.com/hashicorp/nomad/blob/482b49bf1aec006f089bcfc7e632d8f6ac303e5e/drivers/docker/driver.go#L1432-L1468","documentation":"port_map is the legacy Docker-driver mechanism for mapping static network ports from the old single-task network model. It cannot be used with the newer group network block that produces task.Resources.Ports. If a job mixes a group network with port_map, the driver rejects it and directs users to the ports option.","triggerScenarios":"StartTask -> createContainerConfig reaches the default port-resolution branch with len(driverConfig.PortMap) > 0 and task.Resources.Ports != nil (a group network block exists), so port_map and ports/group networking collide.","commonSituations":"Upgrading jobs written for old Nomad task-level networks to group networks while keeping port_map; combining examples from old blog posts with current Nomad job specs.","solutions":["Replace port_map with ports = [\"label1\", \"label2\"] referencing group network port labels","Delete the port_map stanza if group network ports already define the mapping","Split legacy task-level network stanzas into group network blocks with named ports"],"exampleFix":"// before\ndriver {\n  docker {\n    port_map { http = 8080 }\n  }\n}\n// after\ndriver {\n  docker {\n    ports = [\"http\"]\n  }\n}","handlingStrategy":"validation","validationCode":"if len(cfg.PortMap) > 0 && groupHasNetworkBlock {\n  return errors.New(\"use ports = [...] with group networks, not port_map\")\n}","typeGuard":null,"tryCatchPattern":"err := client.StartTask(task); if err != nil && strings.Contains(err.Error(), \"cannot map group network ports\") { migratePortMapToPorts(cfg) }","preventionTips":["Migrate legacy port_map to ports with group network labels","Never combine port_map with group network blocks","Update old job templates"],"tags":["docker","nomad-driver","ports","port-map","legacy"],"backgroundTag":"incompatible-port-config","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"}