testcontainers/testcontainers-java · error · UnsupportedOperationException

Setting a in not supported in the versions below 22.1.0

Error message

Setting a %s in not supported in the versions below 22.1.0

What it means

CockroachContainer throws this UnsupportedOperationException when you call withUsername(), withPassword(), or withDatabaseName() on a CockroachDB image older than 22.1.0. Those versions lack the environment variables Testcontainers uses to configure user, password, and database at startup. The check is done once by parsing the version part of the docker image name against the 22.1.0 threshold.

Solutions

1. Upgrade the image to cockroachdb/cockroach:v22.1.0 or newer (e.g. v23.1.x).
2. If an older image is required, remove the withUsername/withPassword/withDatabaseName calls and rely on the default root user or configure the user inside the container manually.
3. If the tag is actually >= 22.1.0 but formatted unusually, use a standard tag so the version part parses correctly.

Example fix

// before
new CockroachContainer(DockerImageName.parse("cockroachdb/cockroach:v21.2.11"))
    .withUsername("test")
    .withPassword("test")
    .withDatabaseName("db")
// after
new CockroachContainer(DockerImageName.parse("cockroachdb/cockroach:v22.1.0"))
    .withUsername("test")
    .withPassword("test")
    .withDatabaseName("db")

private static final ComparableVersion FIRST_VERSION_WITH_ENV_VARS_SUPPORT = new ComparableVersion("22.1.0");
ComparableVersion v = new ComparableVersion(imageName.getVersionPart().replaceFirst("v", ""));
if (v.isGreaterThanOrEqualTo(FIRST_VERSION_WITH_ENV_VARS_SUPPORT)) {
    container.withUsername("test").withPassword("test").withDatabaseName("db");
}

try {
    container.withUsername("test");
} catch (UnsupportedOperationException e) {
    logger.warn("Image does not support env-var credentials; using defaults", e);
}

When it happens

Trigger: Calling withUsername, withPassword, or withDatabaseName on a container created with an image name whose version part (after stripping the leading 'v') is less than 22.1.0, e.g. cockroachdb/cockroach:v21.2.11.

Common situations: Pinning an older CockroachDB image for version-parity with production; upgrading Testcontainers but keeping an old image tag; a typo or custom registry tag that makes the parsed version appear below 22.1.0.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

• Changing startup timeout is not supported with mode
• Unexpected scheme
• Setting a in not supported in the versions below 22.1.0
• The provided service (service) has no quota to configure
• The Analytics Service is only supported with the Enterprise…

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

Appendix: source

Thrown at modules/cockroachdb/src/main/java/org/testcontainers/containers/CockroachContainer.java:166

        this.password = password;
        return this;
    }

    @Override
    public CockroachContainer withDatabaseName(final String databaseName) {
        validateIfVersionSupportsUsernameOrPasswordOrDatabase("databaseName");
        this.databaseName = databaseName;
        return this;
    }

    private boolean isVersionGreaterThanOrEqualTo221(DockerImageName dockerImageName) {
        ComparableVersion version = new ComparableVersion(dockerImageName.getVersionPart().replaceFirst("v", ""));
        return version.isGreaterThanOrEqualTo(FIRST_VERSION_WITH_ENV_VARS_SUPPORT);
    }

    private void validateIfVersionSupportsUsernameOrPasswordOrDatabase(String parameter) {
        if (!isVersionGreaterThanOrEqualTo221) {
            throw new UnsupportedOperationException(
                String.format("Setting a %s in not supported in the versions below 22.1.0", parameter)
            );
        }
    }

    @Override
    protected void waitUntilContainerStarted() {
        getWaitStrategy().waitUntilReady(this);
    }
}

View on GitHub (pinned to 8e549514e3)