hashicorp/nomad · error

Port %q not found, check network block

Error message

Port %q not found, check network block

What it means

When the docker driver config lists a ports array, every label must resolve to a port declared in the group's network block. If task.Resources.Ports cannot find the given label, the driver rejects the job because it has no host port to publish.

Source

Thrown at drivers/docker/driver.go:1433

			logger.Debug("networking mode not specified; using default")
			hostConfig.NetworkMode = "default"
		}
	}

	// Setup port mapping and exposed ports
	ports := newPublishedPorts(logger)
	switch {
	case task.Resources.Ports != nil && len(driverConfig.Ports) > 0:
		// Do not set up docker port mapping if shared alloc networking is used
		if hostConfig.NetworkMode.IsContainer() {
			break
		}

		for _, port := range driverConfig.Ports {
			if mapping, ok := task.Resources.Ports.Get(port); ok {
				ports.add(mapping.Label, mapping.HostIP, mapping.Value, mapping.To)
			} else {
				return c, fmt.Errorf("Port %q not found, check network block", port)
			}
		}
	case len(task.Resources.NomadResources.Networks) > 0:
		network := task.Resources.NomadResources.Networks[0]

		for _, port := range network.ReservedPorts {
			ports.addMapped(port.Label, network.IP, port.Value, driverConfig.PortMap)
		}

		for _, port := range network.DynamicPorts {
			ports.addMapped(port.Label, network.IP, port.Value, driverConfig.PortMap)
		}

	default:
		if len(driverConfig.PortMap) > 0 {
			if task.Resources.Ports != nil {
				return c, fmt.Errorf("'port_map' cannot map group network ports, use 'ports' instead")
			}

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Ensure every label in the driver's ports list exists in the group's network block port stanza
2. Fix the label spelling so both sides match exactly
3. Declare the missing port in the group network block
4. For dynamic ports, verify the label is the one Nomad assigned, not the numeric value

Example fix

// before
group "app" {
  network { port "http" {} }
  task "web" {
    driver "docker" { ports = ["http", "htpps"] }
  }
}
// after
group "app" {
  network { port "http" {} }
  task "web" {
    driver "docker" { ports = ["http"] }
  }
}

declared := map[string]bool{}
for _, p := range group.Network.Ports { declared[p.Label] = true }
for _, p := range cfg.Ports {
  if !declared[p] {
    return fmt.Errorf("port %q not declared in group network", p)
  }
}

err := client.StartTask(task); if err != nil && strings.Contains(err.Error(), "not found, check network block") { logMissingPortLabel(err) }

When it happens

Trigger: StartTask -> createContainerConfig iterates driverConfig.Ports and task.Resources.Ports.Get(port) returns ok=false for a label not defined in any group network port stanza.

Common situations: Typos between the network port label and the driver's ports list; the port was declared with dynamic=true and its label mismatches; migrating jobs from the old port_map style without updating labels; forgetting the network block entirely.

Related errors

• Trying to map ports but no network interface is available
• failed to parse ipv4_address %q: %v
• invalid value for cpu_cfs_period
• failed to parse security_opt configuration: %v
• failed to parse ulimit configuration: %v

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