testcontainers/testcontainers-java · error · IllegalStateException

Services named do not exist, but wait conditions have been…

Error message

Services named {} {} do not exist, but wait conditions have been defined for them. This might mean that you misspelled the service name when defining the wait condition.

What it means

When a Compose stack starts, ComposeDelegate.waitUntilServiceStarted verifies that every service with a registered wait strategy actually exists among the containers the stack instantiated. If waitStrategyMap has service names that are absent from serviceInstanceMap, it throws IllegalStateException listing the missing services.

Solutions

1. Compare the service name(s) in the exception with the service keys in your docker-compose file
2. Fix the name passed to withExposedService/waitingFor to exactly match the compose service (including case)
3. Remove wait conditions for services that the compose file does not define
4. If using profiles/overrides, ensure the service is actually started in the merged configuration

Example fix

// before
.compose("docker-compose.yml")
.withExposedService("databse_1", 5432, Wait.defaultWaitStrategy())
// after
.compose("docker-compose.yml")
.withExposedService("database_1", 5432, Wait.defaultWaitStrategy())

Set<String> composeServices = parseServiceNamesFromComposeYaml(Paths.get("docker-compose.yml")); waitStrategyNames.forEach(n -> { if (!composeServices.contains(n)) throw new IllegalArgumentException("Unknown compose service: " + n); });

try { composeContainer.start(); } catch (IllegalStateException e) { if (e.getMessage().contains("do not exist, but wait conditions")) { log.error("Fix withExposedService/waitingFor names: {}", e.getMessage()); } throw e; }

When it happens

Trigger: Calling withExposedService("servicename", port) or waitingFor(...) on a DockerComposeContainer with a service name that does not match any service defined in the docker-compose file (names are case-sensitive; scaling can also affect instance naming).

Common situations: Typo or wrong case in the service name (e.g. 'DB' vs 'db'); wait condition referencing a service only started by a different compose profile/override file; service renamed in docker-compose.yml after tests were written.

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

• Could not get a port for
• Changing startup timeout is not supported with mode
• : No exposed ports or mapped ports - cannot wait for status
• This container's image does not have a healthcheck…
• Containerised Docker Compose exited abnormally with code

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

Appendix: source

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

        }

        if (!Strings.isNullOrEmpty(serviceNameArgs)) {
            command += " " + serviceNameArgs;
        }

        // Run the docker compose container, which starts up the services
        runWithCompose(localCompose, command, env, fileCopyInclusions);
    }

    void waitUntilServiceStarted(boolean tailChildContainers) {
        listChildContainers().forEach(container -> createServiceInstance(container, tailChildContainers));

        Set<String> servicesToWaitFor = waitStrategyMap.keySet();
        Set<String> instantiatedServices = serviceInstanceMap.keySet();
        Sets.SetView<String> missingServiceInstances = Sets.difference(servicesToWaitFor, instantiatedServices);

        if (!missingServiceInstances.isEmpty()) {
            throw new IllegalStateException(
                "Services named " +
                missingServiceInstances +
                " " +
                "do not exist, but wait conditions have been defined " +
                "for them. This might mean that you misspelled " +
                "the service name when defining the wait condition."
            );
        }

        serviceInstanceMap.forEach(this::waitUntilServiceStarted);
    }

    private void createServiceInstance(Container container, boolean tailChildContainers) {
        String serviceName = getServiceNameFromContainer(container);
        final ComposeServiceWaitStrategyTarget containerInstance = new ComposeServiceWaitStrategyTarget(
            dockerClient,
            container,
            ambassadorContainer,

View on GitHub (pinned to 8e549514e3)