testcontainers/testcontainers-java · error · IllegalArgumentException

The org.testcontainers namespace is reserved for internal…

Error message

The org.testcontainers namespace is reserved for internal use

What it means

Generic guard in GenericContainer.withLabel: any label key beginning with the reserved 'org.testcontainers' prefix is rejected with IllegalArgumentException, because Testcontainers uses that namespace for internal metadata. The at-fault input is a user-supplied label key under that reserved prefix.

Solutions

1. Use a label key that does not start with 'org.testcontainers'
2. Use your own namespace, e.g. 'com.mycompany.mylabel'

When it happens

Trigger: Thrown at core/src/main/java/org/testcontainers/containers/GenericContainer.java:1118 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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

Appendix: source

Thrown at core/src/main/java/org/testcontainers/containers/GenericContainer.java:1118

        return self();
    }

    /**
     * {@inheritDoc}
     */
    @Override
    public SELF withEnv(Map<String, String> env) {
        env.forEach(this.containerDef::addEnvVar);
        return self();
    }

    /**
     * {@inheritDoc}
     */
    @Override
    public SELF withLabel(String key, String value) {
        if (key.startsWith("org.testcontainers")) {
            throw new IllegalArgumentException("The org.testcontainers namespace is reserved for internal use");
        }
        this.containerDef.addLabel(key, value);
        return self();
    }

    /**
     * {@inheritDoc}
     */
    @Override
    public SELF withLabels(Map<String, String> labels) {
        labels.forEach(this::withLabel);
        return self();
    }

    /**
     * {@inheritDoc}
     */
    @Override

View on GitHub (pinned to 8e549514e3)