testcontainers / testcontainers/testcontainers-java

[Bug]: Image Name Variable Substitution in Compose file Not Performed

Open
#7,893 2 comments 5 reactions 2 assignees View on GitHub

@kiview is already working on this.

Since Aug 20, 2025.

area/docker-compose type/bug type/enhancement
Dominant language
Java
Stars
8.7k
Forks
1.9k
Avg merge
2d 17h
Merged PRs (30d)
9

Description

Module

Core

Testcontainers version

1.19.3

Using the latest Testcontainers version?

Yes

Host OS

Linux

Host Arch

x86-64

Docker version
Client: Docker Engine - Community
 Cloud integration: v1.0.24
 Version:           24.0.7
 API version:       1.43
 Go version:        go1.20.10
 Git commit:        afdd53b
 Built:             Thu Oct 26 09:09:39 2023
 OS/Arch:           linux/amd64
 Context:           default

Server: Docker Engine - Community
 Engine:
  Version:          24.0.7
  API version:      1.43 (minimum version 1.12)
  Go version:       go1.20.10
  Git commit:       311b9ff
  Built:            Thu Oct 26 09:08:11 2023
  OS/Arch:          linux/amd64
  Experimental:     false
 containerd:
  Version:          1.6.25
  GitCommit:        d8f198a4ed8892c764191ef7b3b06d8a2eeb5c7f
 runc:
  Version:          1.1.10
  GitCommit:        v1.1.10-0-g18a0cb0
 docker-init:
  Version:          0.19.0
  GitCommit:        de40ad0
 rootlesskit:
  Version:          1.1.1
  ApiVersion:       1.1.1
  NetworkDriver:    slirp4netns
  PortDriver:       builtin
  StateDir:         /tmp/rootlesskit3454269414
 slirp4netns:
  Version:          1.2.2
  GitCommit:        0ee2d87523e906518d34a6b423271e4826f71faf
What happened?

We're using maven to trigger an integration test. The v2 docker compose plugin ComposeContainer is used like this:
private val environment = ComposeContainer(File("src/test/resources/docker-compose-test.yml")).withLocalCompose(true)

When running maven clean install, every image in the compose file that uses variable expansion causes an error to be generated. Since we're using the local docker compose, this is only a nuisance. However, less experienced users like myself may go down various rabbit holes trying to figure out how to stop these error messages and not realize until later that withPull(false) is needed.

Expected Result
Ideally, variable substitution would be performed in the same manner described by the docker compose documentation. No errors would be generated.

For those using the local docker compose plugin, defaulting pull to be false would help limit confusion. Providing additional context that the local compose plugin will still be performed would be helpful.
Here's the code for withLocalCompose

Relevant log output
2023-11-27 17:10:38.799  INFO   --- [           main] o.t.containers.ComposeDelegate           : Preemptively checking local images for 'confluentinc/cp-server:${TAG_CONFLUENT', referenced via a compose file or transitive Dockerfile. If not available, it will be pulled.
2023-11-27 17:10:38.799  WARN   --- [           main] o.t.containers.ComposeDelegate           : Unable to pre-fetch an image (confluentinc/cp-server:${TAG_CONFLUENT) depended upon by Docker Compose build - startup will continue but may fail. Exception message was: Illegal group reference
2023-11-27 17:10:38.802  INFO   --- [           main] tc.docker                                : Local Docker Compose is running command: compose up -d
Additional Information

No response

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.