quarkusio/quarkus · error · IllegalStateException

Services named ${servicesToWaitFor} do not exist, but wait c

Error message

Services named ${servicesToWaitFor} do not exist, but wait conditions have been defined for them.

What it means

discoverServiceInstances() throws IllegalStateException when checkForRequiredServices is true and some service names registered in servicesToWaitFor (wait conditions) were never found among the containers discovered from the Compose project. It protects against silently waiting forever for services that simply do not exist in the compose file.

Source

Thrown at extensions/devservices/deployment/src/main/java/io/quarkus/devservices/deployment/compose/ComposeProject.java:299

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

    public synchronized void discoverServiceInstances(boolean checkForRequiredServices) {
        Set<String> servicesToWaitFor = new HashSet<>(waitStrategies.keySet());
        List<ComposeServiceWaitStrategyTarget> serviceInstances = new ArrayList<>();
        for (Container container : listChildContainers()) {
            String state = container.getState();
            if ("running".equalsIgnoreCase(state) || "restarting".equalsIgnoreCase(state)) {
                ComposeServiceWaitStrategyTarget instance = createServiceInstance(container, followContainerLogs);
                serviceInstances.add(instance);
                servicesToWaitFor.remove(instance.getServiceName());
            }
        }

        if (checkForRequiredServices && !servicesToWaitFor.isEmpty()) {
            throw new IllegalStateException("Services named " + servicesToWaitFor +
                    " do not exist, but wait conditions have been defined for them.");
        }

        this.networks = listChildNetworks();
        this.serviceInstances = serviceInstances;
    }

    private List<Container> listChildContainers() {
        return dockerClient
                .listContainersCmd()
                .withLabelFilter(Map.of(DOCKER_COMPOSE_PROJECT, project))
                .withShowAll(true)
                .exec();
    }

    private List<Network> listChildNetworks() {
        return dockerClient
                .listNetworksCmd()

View on GitHub (pinned to e1c734241f)

Solutions

1. Align the wait-condition/service names with the actual service keys in the compose file
2. Run 'docker compose config --services' to list valid service names and fix the typo
3. Remove stale wait conditions for services that no longer exist
4. Set checkForRequiredServices=false only if partial discovery is intentionally acceptable (not recommended)

Example fix

# before (application.properties)
quarkus.devservices.services.containers."db".wait-for=port
# compose file defines service 'postgres'
# after
quarkus.devservices.services.containers."postgres".wait-for=port

// verify wait-for names exist in the compose file before starting
Set<String> services = composeServices(dockerComposeYml); // 'docker compose config --services'
for (String wait : configuredWaitFors) {
    if (!services.contains(wait)) throw new IllegalArgumentException("Unknown service: " + wait);
}

try {
    composeProject.start();
} catch (IllegalStateException e) {
    if (e.getMessage().contains("do not exist")) {
        fixServiceNames(e); // realign wait config with compose file
    }
    throw e;
}

When it happens

Trigger: DevServices config declares wait conditions (e.g. quarkus.devservices.services.* or @DockerComposeProject wait-fors) for a service name that no container in the compose file matches — typically a typo or a renamed service.

Common situations: Service renamed in docker-compose.yml without updating the wait config; using the default 'quarkus' service name while the file names the service differently; sharing one compose file across projects with different service names.

Related errors

• Services have not been started yet
• Docker Compose not found. Is ${composeExecutable} on the PAT
• Unsupported port format: ${port}
• Wasn't able to determine the distribution of the search serv
• Failed to load application configuration

AI-assisted analysis of quarkusio/quarkus@e1c734241f (2026-09-05). Data as JSON: /api/errors/2888e3bb3370ea0b. Report an issue: GitHub.