testcontainers/testcontainers-java · error · IllegalArgumentException

A GitHub issue URL must be set for usages of the @Flaky…

Error message

A GitHub issue URL must be set for usages of the @Flaky annotation

What it means

FlakyTestJUnit4RetryRule.apply() validates every @Flaky annotation: a non-empty githubIssueUrl is mandatory so flaky tests are tracked. If the URL is blank, it throws IllegalArgumentException immediately at rule application time.

Solutions

1. Add the tracking GitHub issue URL to the @Flaky annotation
2. Remove the @Flaky annotation if the test is not actually flaky
3. File the issue first, then annotate the test with its URL

Example fix

// before
@Flaky(maxTries = 3)
// after
@Flaky(githubIssueUrl = "https://github.com/org/repo/issues/123", maxTries = 3)

Flaky flaky = m.getAnnotation(Flaky.class);
if (flaky != null && flaky.githubIssueUrl().isBlank()) throw new IllegalStateException("@Flaky requires githubIssueUrl");

When it happens

Trigger: Annotating a test with @Flaky while omitting githubIssueUrl or passing an empty/whitespace string.

Common situations: Developers adding @Flaky quickly to unblock CI without filing the tracking issue; annotation template filled partially; refactors removing the URL.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• @Flaky annotation maxTries must be at least one
• @Flaky reviewDate could not be parsed. Please provide a…
• @Flaky-annotated test failed despite retries.
• FieldName: does not implement Startable
• Container needs to be initialized

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

Appendix: source

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

 *     accompanied by a GitHub issue URL, and should be subject to review at a suitable point in the (near) future.
 *     Should the review date pass without the test's instability being fixed, the retry behaviour will cease to have an
 *     effect and the test will be allowed to sporadically fail again.
 * </p>
 */
@Slf4j
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

View on GitHub (pinned to 8e549514e3)