testcontainers/testcontainers-java · error · ContainerFetchException

Can't get Docker image

Error message

Can't get Docker image: ${image}

What it means

getDockerImageName resolves the configured RemoteDockerImage, which may pull the image from a registry. Any failure during that resolution (network error, missing image/tag, registry auth) is wrapped in ContainerFetchException. It fires when the image cannot actually be fetched, not when the name string is malformed.

Solutions

1. Verify the image name and tag exist in the registry
2. Check network connectivity and registry authentication
3. Pre-pull the image before running tests
4. Inspect the wrapped cause for the root failure

When it happens

Trigger: Thrown at core/src/main/java/org/testcontainers/containers/GenericContainer.java:1308 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/bdfde71e91c1b2ce. Report an issue: GitHub.

Appendix: source

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

    /**
     * {@inheritDoc}
     */
    @Override
    public void setDockerImageName(@NonNull String dockerImageName) {
        this.image = new RemoteDockerImage(dockerImageName);
    }

    /**
     * {@inheritDoc}
     */
    @Override
    @NonNull
    public String getDockerImageName() {
        try {
            return image.get();
        } catch (Exception e) {
            throw new ContainerFetchException("Can't get Docker image: " + image, e);
        }
    }

    /**
     * {@inheritDoc}
     */
    @Override
    @Deprecated
    public String getTestHostIpAddress() {
        if (DockerMachineClient.instance().isInstalled()) {
            try {
                Optional<String> defaultMachine = DockerMachineClient.instance().getDefaultMachine();
                if (!defaultMachine.isPresent()) {
                    throw new IllegalStateException("Could not find a default docker-machine instance");
                }

                String sshConnectionString = CommandLine
                    .runShellCommand("docker-machine", "ssh", defaultMachine.get(), "echo $SSH_CONNECTION")

View on GitHub (pinned to 8e549514e3)