testcontainers/testcontainers-java · error · IllegalArgumentException

Requested port ( ) is not mapped

Error message

Requested port (${originalPort}) is not mapped

What it means

ContainerState.getMappedPort resolves an exposed container port to its host-mapped port from the Docker port bindings. If no binding exists for the requested container port it throws IllegalArgumentException 'Requested port (N) is not mapped'.

Solutions

  1. Expose the port via withExposedPorts(n)/addExposedPorts(n) or ensure the image has EXPOSE and the container publishes it
  2. Call getMappedPort only after container.start() completed
  3. Verify you requested the container-side port, not the host port
  4. For compose containers use getServicePort, which handles service/instance naming

Example fix

// before
GenericContainer c = new GenericContainer<>("redis:7").withExposedPorts(6379);
c.start();
Integer host = c.getMappedPort(6380); // wrong port
// after
Integer host = c.getMappedPort(6379);
Defensive patterns

Strategy: validation

Validate before calling

if (!container.getExposedPorts().contains(containerPort)) throw new IllegalArgumentException("Port " + containerPort + " not exposed; use withExposedPorts first");

Try / catch

try { return container.getMappedPort(port); } catch (IllegalArgumentException e) { throw new IllegalStateException("Port " + port + " is not published on " + container.getContainerInfo().getConfig().getImage(), e); }

Prevention

When it happens

Trigger: Calling getMappedPort(n) where n was never exposed (no withExposedPorts(n)/ExposedPort in the image), before the container started, or for a container using a non-bridge network without published ports.

Common situations: Requesting a port not declared in the image's EXPOSE and not added via withExposedPorts; forgetting addExposedPorts; calling before start(); custom network mode without -p publishing.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

AI-assisted analysis of testcontainers/testcontainers-java@8e549514e3 (2026-09-12). Data as JSON: /api/errors/68e53702032aa933. Report an issue: GitHub.

Appendix: source

Thrown at core/src/main/java/org/testcontainers/containers/ContainerState.java:175

     * @see #getContainerInfo()
     * @see #getCurrentContainerInfo()
     */
    default Integer getMappedPort(int originalPort) {
        Preconditions.checkState(
            this.getContainerId() != null,
            "Mapped port can only be obtained after the container is started"
        );

        Ports.Binding[] binding = new Ports.Binding[0];
        final InspectContainerResponse containerInfo = this.getContainerInfo();
        if (containerInfo != null) {
            binding = containerInfo.getNetworkSettings().getPorts().getBindings().get(new ExposedPort(originalPort));
        }

        if (binding != null && binding.length > 0 && binding[0] != null) {
            return Integer.valueOf(binding[0].getHostPortSpec());
        } else {
            throw new IllegalArgumentException("Requested port (" + originalPort + ") is not mapped");
        }
    }

    /**
     * @return the exposed ports
     */
    List<Integer> getExposedPorts();

    /**
     * @return the port bindings
     */
    default List<String> getPortBindings() {
        List<String> portBindings = new ArrayList<>();
        final Ports hostPortBindings = this.getContainerInfo().getHostConfig().getPortBindings();
        for (Map.Entry<ExposedPort, Ports.Binding[]> binding : hostPortBindings.getBindings().entrySet()) {
            for (Ports.Binding portBinding : binding.getValue()) {
                portBindings.add(String.format("%s:%s", portBinding.toString(), binding.getKey()));
            }

View on GitHub (pinned to 8e549514e3)