[Bug]: Incorrect TESTCONTAINERS_HUB_IMAGE_NAME_PREFIX parsing causes 404 on image pull

[fedorkanin]

Testcontainers version

v0.39.0

Using the latest Testcontainers version?

Yes

Host OS

Linux

Host arch

amd64

Go version

1.25

Docker version

Collapsed

Client:
Version:           28.4.0
API version:       1.51
Go version:        go1.24.7
Git commit:        d8eb465
Built:             Wed Sep  3 20:56:28 2025
OS/Arch:           linux/amd64
Context:           default
Server: Docker Engine - Community
Engine:
Version:          28.4.0
API version:      1.51 (minimum version 1.24)
Go version:       go1.24.7
Git commit:       249d679
Built:            Wed Sep  3 20:58:50 2025
OS/Arch:          linux/amd64
Experimental:     false
containerd:
Version:          v1.7.28
GitCommit:        b98a3aace656320842a23f4a392a33f46af97866
runc:
Version:          1.3.0
GitCommit:        v1.3.0-0-g4ca628d
docker-init:
Version:          0.19.0
GitCommit:        de40ad0

Docker info

Collapsed

Client:
 Version:    28.4.0
 Context:    default
 Debug Mode: false
 Plugins:
  buildx: Docker Buildx (Docker Inc.)
    Version:  v0.28.0
    Path:     /usr/local/libexec/docker/cli-plugins/docker-buildx
  compose: Docker Compose (Docker Inc.)
    Version:  v2.39.2
    Path:     /usr/local/libexec/docker/cli-plugins/docker-compose
Server:
 Containers: 0
  Running: 0
  Paused: 0
  Stopped: 0
 Images: 0
 Server Version: 28.4.0
 Storage Driver: overlay2
  Backing Filesystem: extfs
  Supports d_type: true
  Using metacopy: false
  Native Overlay Diff: true
  userxattr: false

What happened?

Regression caused by #2747.

TL;DR

url.JoinPath used to concat TESTCONTAINERS_HUB_IMAGE_NAME_PREFIX and image tag results in tag being silently dropped if prefix contains a port. Go Playground example.

I then get 404 errors, because testcontainers-go pulls just TESTCONTAINERS_HUB_IMAGE_NAME_PREFIX with no tag. Example of the error:

Error response from daemon: error parsing HTTP 404 response body: unexpected end of JSON input: ""

Long version

I'm trying to use GitLab dependency proxy for container images, so my GitLab CI doesn't exhaust Docker Hub rate limits. GitLab offers several pre-defined variables to access the proxy, including CI_DEPENDENCY_PROXY_DIRECT_GROUP_IMAGE_PREFIX which looks approximately like this: gitlab.mycompany.com:443/mygroup/dependency_proxy/containers.

CI_DEPENDENCY_PROXY_DIRECT_GROUP_IMAGE_PREFIX – the direct group image prefix for pulling images through the Dependency Proxy.

The critical part is that this variable contains a port and does not contain a scheme.

• url.Parse parses urls with a port and no scheme wrongly. GitHub issue. This then results in url.JoinPath ignoring the second argument without an error. Repro in Go Playground.
• Adding an empty // scheme or https scheme in the beginning makes Docker unhappy, as it doesn't expect a scheme. Docker image reference format docs.

Solution

Use path.Join instead of url.JoinPath, as url package does not consider gitlab.mycompany.com:443 to be a valid url.

I will be happy to create a PR.