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

The image requires you to accept a license agreement…

Error message

The image ${imageName} requires you to accept a license agreement. Please place a file at the root of the classpath named ${ACCEPTANCE_FILE_NAME}, e.g. at src/test/resources/${ACCEPTANCE_FILE_NAME}. This file should contain the line:
  ${imageName}

What it means

Some images (e.g. oracle-free/official images like 'oracle', 'mssqlserver') require explicit license acceptance before Testcontainers will start them. LicenseAcceptance.assertLicenseAccepted looks for a file named in ACCEPTANCE_FILE_NAME ('container-license-acceptance.txt') on the classpath containing a line equal to the exact image name; if absent, it throws IllegalStateException with instructions. This enforces the legal requirement to accept the image's license.

Solutions

1. Create src/test/resources/container-license-acceptance.txt containing a line with the exact image name from the message (e.g. mcr.microsoft.com/mssql/server:2022-latest).
2. Ensure the file is on the test runtime classpath (correct source set / module).
3. Verify the line matches the required imageName exactly — including registry, repo and tag — with no extra spaces.

Example fix

// before: missing file
// after: src/test/resources/container-license-acceptance.txt
mcr.microsoft.com/mssql/server:2022-latest

String img = "mcr.microsoft.com/mssql/server:2022-latest";
try (InputStream in = getClass().getResourceAsStream("/container-license-acceptance.txt")) {
    boolean accepted = in != null && new String(in.readAllBytes(), StandardCharsets.UTF_8).lines().anyMatch(l -> l.trim().equals(img));
    if (!accepted) throw new IllegalStateException("License not accepted for " + img);
}

try {
    container.start();
} catch (IllegalStateException e) {
    if (e.getMessage().contains("requires you to accept a license agreement")) {
        log.error("Add image '{}' to container-license-acceptance.txt", e.getMessage().split(" ")[2]);
    }
    throw e;
}

When it happens

Trigger: Starting a licensed container module (e.g. OracleDatabaseContainer, MSSQLServerContainer) without a container-license-acceptance.txt on the classpath containing the full image name including tag.

Common situations: Forgetting the file after adding a licensed module; file exists but image string doesn't match exactly (missing tag, different registry, whitespace); file placed in wrong source set; new image version added to tests without updating the acceptance file.

Understand the failure class

Background: "X is required", "must be set", "cannot be empty": the missing-required-config error family, from Vertex AI project/location to WeChat keys — this error's family across 18 libraries.

Related errors

• Can't transfer
• Configured Image Substitutor could not be loaded
• Resource with path could not be found on any of these…
• Failed to process JAR file when extracting classpath…
• Could not load classpath init script

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

Appendix: source

Thrown at core/src/main/java/org/testcontainers/utility/LicenseAcceptance.java:30

 */
@UtilityClass
public class LicenseAcceptance {

    private static final String ACCEPTANCE_FILE_NAME = "container-license-acceptance.txt";

    public static void assertLicenseAccepted(final String imageName) {
        try {
            final URL url = Resources.getResource(ACCEPTANCE_FILE_NAME);
            final List<String> acceptedLicences = Resources.readLines(url, Charsets.UTF_8);

            if (acceptedLicences.stream().map(String::trim).anyMatch(imageName::equals)) {
                return;
            }
        } catch (Exception ignored) {
            // suppressed
        }

        throw new IllegalStateException(
            "The image " +
            imageName +
            " requires you to accept a license agreement. " +
            "Please place a file at the root of the classpath named " +
            ACCEPTANCE_FILE_NAME +
            ", e.g. at " +
            "src/test/resources/" +
            ACCEPTANCE_FILE_NAME +
            ". This file should contain the line:\n  " +
            imageName
        );
    }
}

View on GitHub (pinned to 8e549514e3)