testcontainers/testcontainers-java · error · IllegalArgumentException

Could not get a port for

Error message

Could not get a port for '${serviceName}'. Testcontainers does not have an exposed port configured for '${serviceName}'. To fix, please ensure that the service '${serviceName}' has ports exposed using .withExposedService(...)

What it means

ComposeDelegate.getServicePort looks up the ambassador/port mapping registered for a compose service. If no port mapping exists for that service it throws IllegalArgumentException explaining that no exposed port was configured for the service.

Solutions

1. Register the service with .withExposedService(serviceName, port) on the DockerComposeContainer before getServicePort
2. Ensure the serviceName passed to getServicePort matches the one used in withExposedService
3. Ensure the compose container is started (ports map is populated during start)
4. Alternatively read the port from the service's wait strategy / container directly

Example fix

// before
Integer port = compose.getServicePort("redis", 6379); // never exposed
// after
DockerComposeContainer compose = new DockerComposeContainer(new File("docker-compose.yml"))
    .withExposedService("redis_1", 6379, Wait.defaultWaitStrategy());
compose.start();
Integer port = compose.getServicePort("redis_1", 6379);

if (!exposedServices.containsKey(serviceName)) throw new IllegalStateException("Call withExposedService for " + serviceName + " before getServicePort");

try { return compose.getServicePort(serviceName, port); } catch (IllegalArgumentException e) { throw new IllegalStateException("Service not exposed on compose container: " + serviceName, e); }

When it happens

Trigger: Calling getServicePort(serviceName, port) on a DockerComposeContainer for a service that was never registered via withExposedService, or with a wrong service name, before the mapping exists.

Common situations: Querying a service you forgot to expose with withExposedService; misspelled service name; calling getServicePort for a service started outside the compose container; reading the port before startup finished.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

• Services named do not exist, but wait conditions have been…
• Requested port ( ) is not mapped
• Containerised Docker Compose exited abnormally with code
• Local Docker Compose not found. Is
• Local Docker Compose exited abnormally with code

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

Appendix: source

Thrown at core/src/main/java/org/testcontainers/containers/ComposeDelegate.java:348

        );
        waitAllStrategy.withStrategy(waitStrategy);
    }

    /**
     * Get the port that an exposed service can be found at, from the host machine
     * (i.e. should be the machine that's running this Java process).
     * <p>
     * The service must have been declared using DockerComposeContainer#withExposedService.
     *
     * @param serviceName the name of the service as set in the docker-compose.yml file.
     * @param servicePort the port exposed by the service container.
     * @return a port that can be used for accessing the service container.
     */
    public Integer getServicePort(String serviceName, Integer servicePort) {
        Map<Integer, Integer> portMap = this.ambassadorPortMappings.get(getServiceInstanceName(serviceName));

        if (portMap == null) {
            throw new IllegalArgumentException(
                "Could not get a port for '" +
                serviceName +
                "'. " +
                "Testcontainers does not have an exposed port configured for '" +
                serviceName +
                "'. " +
                "To fix, please ensure that the service '" +
                serviceName +
                "' has ports exposed using .withExposedService(...)"
            );
        } else {
            return ambassadorContainer.getMappedPort(portMap.get(servicePort));
        }
    }

    Optional<ContainerState> getContainerByServiceName(String serviceName) {
        String serviceInstantName = getServiceInstanceName(serviceName);
        return Optional.ofNullable(serviceInstanceMap.get(serviceInstantName));

View on GitHub (pinned to 8e549514e3)