testcontainers/testcontainers-java · error · IllegalStateException

Compose file has 'container_name' property set for service…

Error message

Compose file ${composeFileName} has 'container_name' property set for service '${serviceName}' but this property is not supported by Testcontainers, consider removing it

What it means

Testcontainers requires unique, dynamically generated container names, so a compose service declaring `container_name` breaks container reuse and network identity. parseAndValidate() rejects any service definition containing that key with an IllegalStateException telling the developer to remove it.

Solutions

1. Remove the `container_name` key from each service in the compose file.
2. Reference services by service name instead of container name (Testcontainers registers network aliases per service).
3. Keep a separate trimmed compose file for tests if the same file must serve local runs.

Example fix

# before
services:
  db:
    image: postgres:16
    container_name: my-postgres
# after
services:
  db:
    image: postgres:16

String yaml = Files.readString(file.toPath());
if (yaml.contains("container_name:")) throw new IllegalStateException("remove container_name before using with Testcontainers");

try { new ParsedDockerComposeFile(file); } catch (IllegalStateException e) { throw new ConfigurationException("Compose file invalid for Testcontainers: " + e.getMessage(), e); }

When it happens

Trigger: A compose file passed to DockerComposeContainer/ParsedDockerComposeFile contains, under any service, the key `container_name: <name>`. The check runs for every service during parseAndValidate().

Common situations: Reusing a compose file written for plain `docker-compose up` where container_name was set for networking or log correlation; copying examples from the internet that set container_name.

Related errors

• Unable to parse YAML file from
• is not a valid Docker image name (in )
• is not a valid image versioning identifier (in )
• anyOthers parameter must be non-empty
• The number of replicas must be between 0 and 3 (inclusive)

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

Appendix: source

Thrown at core/src/main/java/org/testcontainers/containers/ParsedDockerComposeFile.java:134

                    "Compose file {} has an unknown format: service '{}' is not Map",
                    composeFileName,
                    serviceName
                );
                break;
            }

            @SuppressWarnings("unchecked")
            final Map<String, ?> serviceDefinitionMap = (Map<String, ?>) serviceDefinition;

            validateNoContainerNameSpecified(serviceName, serviceDefinitionMap);
            findServiceImageName(serviceName, serviceDefinitionMap);
            findImageNamesInDockerfile(serviceName, serviceDefinitionMap);
        }
    }

    private void validateNoContainerNameSpecified(String serviceName, Map<String, ?> serviceDefinitionMap) {
        if (serviceDefinitionMap.containsKey("container_name")) {
            throw new IllegalStateException(
                String.format(
                    "Compose file %s has 'container_name' property set for service '%s' but this property is not supported by Testcontainers, consider removing it",
                    composeFileName,
                    serviceName
                )
            );
        }
    }

    private void findServiceImageName(String serviceName, Map<String, ?> serviceDefinitionMap) {
        Object result = serviceDefinitionMap.get("image");
        if (result instanceof String) {
            final String imageName = (String) result;
            log.debug("Resolved dependency image for Docker Compose in {}: {}", composeFileName, imageName);
            serviceNameToImageNames.put(serviceName, Sets.newHashSet(imageName));
        }
    }

View on GitHub (pinned to 8e549514e3)