What causes "Retrying @Flaky-annotated test: {}" in testcontainers/testcontainers-java?

Fix the underlying flakiness: use Awaitility/polling instead of fixed sleeps and assert after the container is ready.

testcontainers/testcontainers-java · warning

Retrying @Flaky-annotated test

Error message

Retrying @Flaky-annotated test: {}

What it means

FlakyTestJUnit4RetryRule.evaluate logs this warning each time a test annotated @Flaky fails and is retried, up to maxTries attempts. The rule swallows each failure into a causes list and re-runs base.evaluate(); only when all retries are exhausted does it throw IllegalStateException. Seeing this message repeatedly means a test is genuinely failing and being papered over.

Solutions

Fix the underlying flakiness: use Awaitility/polling instead of fixed sleeps and assert after the container is ready.
Inspect the final IllegalStateException's collected causes for the root failure of the last attempt.
Remove @Flaky so the failure is surfaced immediately rather than retried and hidden.

Example fix

// before
@Test @Flaky
public void pollsService() { assertServiceUp(); } // fails intermittently
// after
@Test
public void pollsService() {
    await().atMost(Duration.ofSeconds(30)).untilAsserted(this::assertServiceUp);
}

Defensive patterns

Strategy: retry

Validate before calling

// pre-flight: ensure container is ready before the test runs
container.isRunning();

Try / catch

try {
    rule.apply(base, description).evaluate();
} catch (IllegalStateException e) {
    // all retries exhausted; inspect e for aggregated causes
    log.error("Flaky test failed after retries", e);
    throw e;
}

Prevention

Replace fixed sleeps with Awaitility/polling assertions
Investigate the aggregated causes instead of relying on retries
Remove @Flaky once the test is stabilized so failures surface immediately

When it happens

Trigger: A @Flaky-annotated JUnit4 test throwing any Throwable during base.evaluate() while FlakyTestJUnit4RetryRule is applied; the rule retries and logs this warning per failed attempt.

Common situations: Flaky integration tests hitting timing/race issues (e.g. waiting on containers); network hiccups against testcontainers-hosted services; asserting on eventually-consistent state.

Related errors

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

Appendix: source

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

        private final int maxTries;

        RetryingStatement(Statement base, Description description, int maxTries) {
            this.base = base;
            this.description = description;
            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)