testcontainers/testcontainers-java · error · java.lang.IllegalArgumentException

is not a valid image versioning identifier (in )

Error message

${versioning} is not a valid image versioning identifier (in ${rawName})

What it means

DockerImageName.assertValid() checks that the versioning part (tag and/or digest) is syntactically valid. If not, it throws IllegalArgumentException stating the versioning identifier is invalid, including the original raw name. This catches malformed tags/digests before they reach the Docker daemon.

Solutions

  1. Fix the tag/digest in the rawName shown in the message to a valid Docker tag or a 'sha256:<hex>' digest.
  2. Remove stray ':' or '@' separators produced by empty interpolated variables.
  3. Pre-validate tags with a regex or DockerImageName.parse(...).assertValid() before use.

Example fix

// before
DockerImageName.parse("postgres:" + version + "@" + digest).assertValid(); // digest lacked 'sha256:'
// after
DockerImageName.parse("postgres:" + version + "@sha256:" + digest).assertValid();
Defensive patterns

Strategy: validation

Validate before calling

static final Pattern TAG = Pattern.compile("^[A-Za-z0-9_][A-Za-z0-9._-]{0,127}$");
static final Pattern DIGEST = Pattern.compile("^[A-Za-z][A-Za-z0-9]*(?:[-_+.][A-Za-z][A-Za-z0-9]*)*:[0-9a-fA-F]{32,}$");
if (!TAG.matcher(tag).matches() && !DIGEST.matcher(tag).matches()) throw new IllegalArgumentException("Bad tag/digest: " + tag);

Try / catch

try {
    imageName.assertValid();
} catch (IllegalArgumentException e) {
    throw new IllegalArgumentException("Invalid image tag/digest: " + e.getMessage(), e);
}

Prevention

When it happens

Trigger: Calling assertValid() on a parsed image whose tag contains illegal characters, is malformed, or whose digest is not a proper algorithm:hex digest (e.g. 'repo@deadbeef' or 'name:@tag!').

Common situations: String interpolation producing '@' or ':' with empty/invalid parts; hand-built digests missing the sha256: prefix; tags with special characters copied from URLs.

Understand the failure class

Background: "invalid id" errors: invalid identifier format — why libraries reject IDs before lookup, and how to fix them — this error's family across 37 libraries.

Related errors

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

Appendix: source

Thrown at core/src/main/java/org/testcontainers/utility/DockerImageName.java:219

    @Override
    public String toString() {
        return asCanonicalNameString();
    }

    /**
     * Is the image name valid?
     *
     * @throws IllegalArgumentException if not valid
     */
    public void assertValid() {
        //noinspection UnstableApiUsage
        HostAndPort.fromString(registry); // return value ignored - this throws if registry is not a valid host:port string
        if (!REPO_NAME.matcher(repository).matches()) {
            throw new IllegalArgumentException(repository + " is not a valid Docker image name (in " + rawName + ")");
        }
        if (!versioning.isValid()) {
            throw new IllegalArgumentException(
                versioning + " is not a valid image versioning identifier (in " + rawName + ")"
            );
        }
    }

    /**
     * @param newTag version tag for the copy to use
     * @return an immutable copy of this {@link DockerImageName} with the new version tag
     */
    public DockerImageName withTag(final String newTag) {
        return withVersioning(new TagVersioning(newTag));
    }

    /**
     * Declare that this {@link DockerImageName} is a compatible substitute for another image - i.e. that this image
     * behaves as the other does, and is compatible with Testcontainers' assumptions about the other image.
     *
     * @param otherImageName the image name of the other image

View on GitHub (pinned to 8e549514e3)