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

anyOthers parameter must be non-empty

Error message

anyOthers parameter must be non-empty

What it means

DockerImageName.assertCompatibleWith(DockerImageName... anyOthers) requires at least one candidate image to compare against. If called with an empty varargs array it immediately throws IllegalArgumentException('anyOthers parameter must be non-empty'). This is a programming-error guard: compatibility checking is meaningless with no candidate images.

Solutions

1. Pass at least one expected image, e.g. assertCompatibleWith(DockerImageName.parse("postgres:16")) for the official one.
2. Guard the call site: only call assertCompatibleWith when the candidates list is non-empty, and otherwise fail with your own clearer message.
3. Fix the source of the empty list (missing constant/config) rather than suppressing the call.

Example fix

// before
if (compatibles.isEmpty()) image.assertCompatibleWith(); // wrong
// after
if (!compatibles.isEmpty()) {
    image.assertCompatibleWith(compatibles.toArray(new DockerImageName[0]));
}

if (candidates == null || candidates.isEmpty()) {
    throw new IllegalStateException("No compatibility candidates configured for " + imageName);
}

try {
    base.assertCompatibleWith(candidates.toArray(new DockerImageName[0]));
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("non-empty")) {
        throw new IllegalStateException("Compatibility candidate list was empty — check config", e);
    }
    throw e;
}

When it happens

Trigger: Calling image.assertCompatibleWith() with no arguments, or spreading an empty collection: image.assertCompatibleWith(compatibles.toArray(new DockerImageName[0])) where compatibles is empty.

Common situations: Building the varargs list from configuration/constants that end up empty; refactoring away a literal argument; passing an empty array from a helper method.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• is not a valid Docker image name (in )
• is not a valid image versioning identifier (in )
• The number of replicas must be between 0 and 3 (inclusive)
• This container's image does not have a healthcheck…
• Compose file has 'container_name' property set for service…

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

Appendix: source

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

            return false;
        }

        return this.compatibleSubstituteFor.isCompatibleWith(other);
    }

    /**
     * Behaves as {@link DockerImageName#isCompatibleWith(DockerImageName)} but throws an exception
     * rather than returning false if a mismatch is detected.
     *
     * @param anyOthers the other image(s) that we are trying to check compatibility with. If more
     *                  than one is provided, this method will check compatibility with at least one
     *                  of them.
     * @throws IllegalStateException if {@link DockerImageName#isCompatibleWith(DockerImageName)}
     *                               returns false
     */
    public void assertCompatibleWith(DockerImageName... anyOthers) {
        if (anyOthers.length == 0) {
            throw new IllegalArgumentException("anyOthers parameter must be non-empty");
        }

        for (DockerImageName anyOther : anyOthers) {
            if (this.isCompatibleWith(anyOther)) {
                return;
            }
        }

        final DockerImageName exampleOther = anyOthers[0];

        throw new IllegalStateException(
            String.format(
                "Failed to verify that image '%s' is a compatible substitute for '%s'. This generally means that " +
                "you are trying to use an image that Testcontainers has not been designed to use. If this is " +
                "deliberate, and if you are confident that the image is compatible, you should declare " +
                "compatibility in code using the `asCompatibleSubstituteFor` method. For example:\n" +
                "   DockerImageName myImage = DockerImageName.parse(\"%s\").asCompatibleSubstituteFor(\"%s\");\n" +
                "and then use `myImage` instead.",

View on GitHub (pinned to 8e549514e3)