testcontainers/testcontainers-java · error · IllegalArgumentException

@Flaky annotation maxTries must be at least one

Error message

@Flaky annotation maxTries must be at least one

What it means

FlakyTestJUnit4RetryRule enforces that maxTries is at least 1; a value below 1 would make the retry rule meaningless (the test would never run). It throws IllegalArgumentException at rule application time.

Solutions

  1. Set maxTries to a value >= 1 (typically 2-5)
  2. Remove @Flaky entirely to disable retries
  3. Use JUnit's @Ignore if the intent was to skip the test

Example fix

// before
@Flaky(githubIssueUrl = "...", maxTries = 0)
// after
@Flaky(githubIssueUrl = "...", maxTries = 3)
Defensive patterns

Strategy: validation

Validate before calling

Flaky flaky = m.getAnnotation(Flaky.class);
if (flaky != null && flaky.maxTries() < 1) throw new IllegalStateException("maxTries must be >= 1");

Prevention

When it happens

Trigger: Declaring @Flaky(maxTries = 0) or a negative maxTries on a test method.

Common situations: Copy-paste of the annotation with placeholder values; attempts to 'disable' a flaky test by setting maxTries to 0 instead of removing the annotation.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

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

Appendix: source

Thrown at test-support/src/main/java/org/testcontainers/testsupport/FlakyTestJUnit4RetryRule.java:48

public class FlakyTestJUnit4RetryRule implements TestRule {

    @Override
    public Statement apply(Statement base, Description description) {
        final Flaky annotation = description.getAnnotation(Flaky.class);

        if (annotation == null) {
            // leave the statement as-is
            return base;
        }

        if (annotation.githubIssueUrl().trim().length() == 0) {
            throw new IllegalArgumentException("A GitHub issue URL must be set for usages of the @Flaky annotation");
        }

        final int maxTries = annotation.maxTries();

        if (maxTries < 1) {
            throw new IllegalArgumentException("@Flaky annotation maxTries must be at least one");
        }

        final LocalDate reviewDate;
        try {
            reviewDate = LocalDate.parse(annotation.reviewDate());
        } catch (DateTimeParseException e) {
            throw new IllegalArgumentException(
                "@Flaky reviewDate could not be parsed. Please provide a date in yyyy-mm-dd format"
            );
        }

        // the annotation should only have an effect before the review date, to encourage review and resolution
        if (LocalDate.now().isBefore(reviewDate)) {
            return new RetryingStatement(base, description, maxTries);
        } else {
            return base;
        }
    }

View on GitHub (pinned to 8e549514e3)