testcontainers/testcontainers-java · critical · IllegalStateException

@Flaky-annotated test failed despite retries.

Error message

@Flaky-annotated test failed despite retries.

What it means

After exhausting all retry attempts for an @Flaky-annotated test, FlakyTestJUnit4RetryRule.evaluate() throws IllegalStateException ('@Flaky-annotated test failed despite retries.') wrapping a MultipleFailureException of every attempt's cause. It means the test genuinely failed on every allowed retry.

Solutions

1. Read the aggregated causes in MultipleFailureException to find the consistent root failure
2. Fix the underlying test/product bug — it is no longer intermittent
3. File/move the GitHub issue referenced by @Flaky to a bug
4. Increase maxTries only if evidence shows failures are still intermittent

try { rule.apply(base, description).evaluate(); } catch (IllegalStateException e) { Throwable aggregated = e.getCause(); /* MultipleFailureException: inspect each attempt */ }

When it happens

Trigger: A test annotated @Flaky fails maxTries times in a row — the flakiness has become a deterministic failure or the underlying issue worsened.

Common situations: A flaky test regressed into a hard failure; environment-dependent flakiness (port conflicts, timing) persists across retries; maxTries set too low for real intermittency.

Related errors

• A GitHub issue URL must be set for usages of the @Flaky…
• @Flaky annotation maxTries must be at least one
• @Flaky reviewDate could not be parsed. Please provide a…
• Retrying @Flaky-annotated test
• FieldName: does not implement Startable

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

Appendix: source

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

            this.maxTries = maxTries;
        }

        @Override
        public void evaluate() {
            int attempts = 0;
            final List<Throwable> causes = new ArrayList<>();

            while (++attempts <= maxTries) {
                try {
                    base.evaluate();
                    return;
                } catch (Throwable throwable) {
                    log.warn("Retrying @Flaky-annotated test: {}", description.getDisplayName());
                    causes.add(throwable);
                }
            }

            throw new IllegalStateException(
                "@Flaky-annotated test failed despite retries.",
                new MultipleFailureException(causes)
            );
        }
    }
}

View on GitHub (pinned to 8e549514e3)