[Bug]: DockerImageName can't handle names in the form foo:tag@sha256:acbd

[tomdcc]

Module

Core

Testcontainers version

1.21.4

Using the latest Testcontainers version?

Yes

Host OS

Linux, Mac

Host Arch

x86, ARM

Docker version

Client:
 Version:           28.5.1
 API version:       1.51
 Go version:        go1.24.8
 Git commit:        e180ab8
 Built:             Wed Oct  8 12:16:17 2025
 OS/Arch:           darwin/arm64
 Context:           desktop-linux

Server: Docker Desktop 4.48.0 (207573)
 Engine:
  Version:          28.5.1
  API version:      1.51 (minimum version 1.24)
  Go version:       go1.24.8
  Git commit:       f8215cc
  Built:            Wed Oct  8 12:18:25 2025
  OS/Arch:          linux/arm64
  Experimental:     false
 containerd:
  Version:          1.7.27
  GitCommit:        05044ec0a9a75232cad458027ca83437aae3f4da
 runc:
  Version:          1.2.5
  GitCommit:        v1.2.5-0-g59923ef
 docker-init:
  Version:          0.19.0
  GitCommit:        de40ad0

What happened?

DockerImageName can't handle names in the form foo:tag@sha256:acbd. Ie the following throws:

DockerImageName.parse("foo:tag@sha256:acbd").assertValid()

This is a valid format. Although it's logically the same as omitting the tag, this form is often used so that tooling like Renovate can suggest updated image checksums when the target tag is updated. Or alternatively a human can do the same thing manually

So e.g. if we have a name like alpine:3.22@sha256:765942a4039992336de8dd5db680586e1a206607dd06170ff0a37267a9e01958 we would like to regularly update the checksum as newer versions are published and the tag is pointed to the latest images.

Currently I've put in a workaround to strip the tag out before handing the name to DockerImageFile.parse() but this should not be necessary given that this is a widely used image name format.

Relevant log output

java.lang.IllegalArgumentException: alpine:3.23 is not a valid Docker image name (in alpine:3.23@sha256:51183f2cfa6320055da30872f211093f9ff1d3cf06f39a0bdb212314c5dc7375)
	at app//org.testcontainers.utility.DockerImageName.assertValid(DockerImageName.java:185)
	at com.foo.ImageNameTest.parse image name(ImageNameTest.groovy:84)

Additional Information

No response

[eddumelendez]

Hi, please next time check if there is already a similar issue.

[tomdcc]

The attempted fix attached to that issue only alters DockerImageName.isCompatibleWith() - but parse() still puts the wrong value into the repository field and assertValid() and everything associated with it will still fail. So this is reporting a slightly different issue. But if it's understood that the root cause is the same no worries. 👍