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

is not a valid Docker image name (in )

Error message

${repository} is not a valid Docker image name (in ${rawName})

What it means

DockerImageName.assertValid() validates that the parsed repository part matches Docker's repository-name regex. If it doesn't, it throws IllegalArgumentException stating the repository is not a valid Docker image name, including the original raw name. This guards against images with malformed names being sent to the Docker daemon.

Solutions

  1. Check the rawName in the message and fix the image string to a valid Docker repository name (lowercase alphanumerics, '.', '_', '/', optional registry).
  2. Uppercase is only allowed in the registry host part — lowercase the repository portion or move the case-sensitive part into a tag/label.
  3. Validate the name early with DockerImageName.parse(raw).assertValid() in your own setup code to fail fast with context.

Example fix

// before
DockerImageName.parse("MyApp:1.0").assertValid();
// after
DockerImageName.parse("myapp:1.0").assertValid();
Defensive patterns

Strategy: validation

Validate before calling

static final Pattern REPO = Pattern.compile("^[a-z0-9]+(?:(?:[._]|__|[-]*)[a-z0-9]+)*(?:/[a-z0-9]+(?:(?:[._]|__|[-]*)[a-z0-9]+)*)*$");
if (!REPO.matcher(repository).matches()) throw new IllegalArgumentException("Invalid repo: " + repository);

Try / catch

try {
    imageName.assertValid();
} catch (IllegalArgumentException e) {
    throw new IllegalArgumentException("Fix image name: " + e.getMessage(), e);
}

Prevention

When it happens

Trigger: Calling DockerImageName.parse(...).assertValid() (directly or transitively when a container starts) with a name whose repository portion violates Docker naming rules — uppercase letters in the repo path, illegal characters, empty segments, etc.

Common situations: Typo'd image names with uppercase (e.g. 'MyApp:latest'); interpolated variables left empty producing names like '/:tag'; mistaking registry-qualified names for repo rules; concatenating prefix strings incorrectly.

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/e54d122705b8bca4. Report an issue: GitHub.

Appendix: source

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

        }
        return getUnversionedPart() + versioning.getSeparator() + getVersionPart();
    }

    @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

View on GitHub (pinned to 8e549514e3)