{"record":{"id":"1c3d39cd2fa6e7c6","repo":"testcontainers/testcontainers-java","slug":"versioning-is-not-a-valid-image-versioning-identifier-in","errorCode":null,"errorMessage":"${versioning} is not a valid image versioning identifier (in ${rawName})","messagePattern":"(.+?) is not a valid image versioning identifier \\(in (.+?)\\)","errorType":"exception","errorClass":"java.lang.IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"core/src/main/java/org/testcontainers/utility/DockerImageName.java","lineNumber":219,"sourceCode":"\n    @Override\n    public String toString() {\n        return asCanonicalNameString();\n    }\n\n    /**\n     * Is the image name valid?\n     *\n     * @throws IllegalArgumentException if not valid\n     */\n    public void assertValid() {\n        //noinspection UnstableApiUsage\n        HostAndPort.fromString(registry); // return value ignored - this throws if registry is not a valid host:port string\n        if (!REPO_NAME.matcher(repository).matches()) {\n            throw new IllegalArgumentException(repository + \" is not a valid Docker image name (in \" + rawName + \")\");\n        }\n        if (!versioning.isValid()) {\n            throw new IllegalArgumentException(\n                versioning + \" is not a valid image versioning identifier (in \" + rawName + \")\"\n            );\n        }\n    }\n\n    /**\n     * @param newTag version tag for the copy to use\n     * @return an immutable copy of this {@link DockerImageName} with the new version tag\n     */\n    public DockerImageName withTag(final String newTag) {\n        return withVersioning(new TagVersioning(newTag));\n    }\n\n    /**\n     * Declare that this {@link DockerImageName} is a compatible substitute for another image - i.e. that this image\n     * behaves as the other does, and is compatible with Testcontainers' assumptions about the other image.\n     *\n     * @param otherImageName the image name of the other image","sourceCodeStart":201,"sourceCodeEnd":237,"githubUrl":"https://github.com/testcontainers/testcontainers-java/blob/8e549514e3f01c57d70546fbb8599d138f3903e5/core/src/main/java/org/testcontainers/utility/DockerImageName.java#L201-L237","documentation":"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.","triggerScenarios":"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!').","commonSituations":"String interpolation producing '@' or ':' with empty/invalid parts; hand-built digests missing the sha256: prefix; tags with special characters copied from URLs.","solutions":["Fix the tag/digest in the rawName shown in the message to a valid Docker tag or a 'sha256:<hex>' digest.","Remove stray ':' or '@' separators produced by empty interpolated variables.","Pre-validate tags with a regex or DockerImageName.parse(...).assertValid() before use."],"exampleFix":"// before\nDockerImageName.parse(\"postgres:\" + version + \"@\" + digest).assertValid(); // digest lacked 'sha256:'\n// after\nDockerImageName.parse(\"postgres:\" + version + \"@sha256:\" + digest).assertValid();","handlingStrategy":"validation","validationCode":"static final Pattern TAG = Pattern.compile(\"^[A-Za-z0-9_][A-Za-z0-9._-]{0,127}$\");\nstatic final Pattern DIGEST = Pattern.compile(\"^[A-Za-z][A-Za-z0-9]*(?:[-_+.][A-Za-z][A-Za-z0-9]*)*:[0-9a-fA-F]{32,}$\");\nif (!TAG.matcher(tag).matches() && !DIGEST.matcher(tag).matches()) throw new IllegalArgumentException(\"Bad tag/digest: \" + tag);","typeGuard":null,"tryCatchPattern":"try {\n    imageName.assertValid();\n} catch (IllegalArgumentException e) {\n    throw new IllegalArgumentException(\"Invalid image tag/digest: \" + e.getMessage(), e);\n}","preventionTips":["Guard interpolated version variables against empty values","Always prefix digests with sha256:","Keep tags <=128 chars, alphanumerics plus ._- only"],"tags":["validation","docker-image","tag"],"backgroundTag":"invalid-identifier-format","analyzedSha":"8e549514e3f01c57d70546fbb8599d138f3903e5","analyzedAt":"2026-09-12T14:56:41.227Z","contentChangedAt":"2026-09-12T14:56:41.227Z","schemaVersion":2},"datasetVersion":"2026-09-16T04:17:20.429Z"}