hashicorp/nomad · error

port map out of bounds

Error message

port map out of bounds

What it means

Driver server guard in StartTask: a port map value exceeds math.MaxInt32 and cannot be stored in the int32 field of the protobuf NetworkOverride, so the request is rejected before reaching the driver.

Source

Thrown at plugins/drivers/server.go:157

			if err != nil {
				// If this error, it will always error
				panic(err)
			}
			return nil, st.Err()
		}
		return nil, err
	}

	var pbNet *proto.NetworkOverride
	if net != nil {
		pbNet = &proto.NetworkOverride{
			PortMap:       map[string]int32{},
			Addr:          net.IP,
			AutoAdvertise: net.AutoAdvertise,
		}
		for k, v := range net.PortMap {
			if v > math.MaxInt32 {
				return nil, fmt.Errorf("port map out of bounds")
			}
			pbNet.PortMap[k] = int32(v)
		}
	}

	resp := &proto.StartTaskResponse{
		Handle:          taskHandleToProto(handle),
		NetworkOverride: pbNet,
	}

	return resp, nil
}

func (b *driverPluginServer) WaitTask(ctx context.Context, req *proto.WaitTaskRequest) (*proto.WaitTaskResponse, error) {
	ch, err := b.impl.WaitTask(ctx, req.TaskId)
	if err != nil {
		return nil, err
	}

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Use port values within the valid 32-bit range (realistically 1-65535)
2. Fix the jobspec/JVM override that produced the oversized port number

When it happens

Trigger: Thrown at plugins/drivers/server.go:157 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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