testcontainers/testcontainers-java · error · ContainerLaunchException

Aborting attempt to link to container

Error message

Aborting attempt to link to container ${containerName} as it is not running

What it means

Thrown during container startup while applyConfiguration builds the Docker create command: a link was requested (via withLinkedContainer) to a peer container that is not currently running, so the link is aborted. It fires because legacy Docker --link requires the target container to be up at configuration time.

Solutions

1. Ensure the linked container is started before this container is started
2. Reorder container lifecycle so dependencies start first
3. Use a shared Docker network instead of legacy container links

When it happens

Trigger: Thrown at core/src/main/java/org/testcontainers/containers/GenericContainer.java:794 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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

Appendix: source

Thrown at core/src/main/java/org/testcontainers/containers/GenericContainer.java:794

    private void applyConfiguration(CreateContainerCmd createCommand) {
        this.containerDef.applyTo(createCommand);
        buildHostConfig(createCommand.getHostConfig());

        VolumesFrom[] volumesFromsArray = volumesFroms.stream().toArray(VolumesFrom[]::new);
        createCommand.withVolumesFrom(volumesFromsArray);

        Set<Link> allLinks = new HashSet<>();
        Set<String> allLinkedContainerNetworks = new HashSet<>();
        for (Entry<String, LinkableContainer> linkEntries : linkedContainers.entrySet()) {
            String alias = linkEntries.getKey();
            LinkableContainer linkableContainer = linkEntries.getValue();

            Set<Link> links = findLinksFromThisContainer(alias, linkableContainer);
            allLinks.addAll(links);

            if (allLinks.size() == 0) {
                throw new ContainerLaunchException(
                    "Aborting attempt to link to container " +
                    linkableContainer.getContainerName() +
                    " as it is not running"
                );
            }

            Set<String> linkedContainerNetworks = findAllNetworksForLinkedContainers(linkableContainer);
            allLinkedContainerNetworks.addAll(linkedContainerNetworks);
        }

        createCommand.withLinks(allLinks.toArray(new Link[allLinks.size()]));

        allLinkedContainerNetworks.remove("bridge");
        if (allLinkedContainerNetworks.size() > 1) {
            logger()
                .warn(
                    "Container needs to be on more than one custom network to link to other " +
                    "containers - this is not currently supported. Required networks are: {}",

View on GitHub (pinned to 8e549514e3)