testcontainers/testcontainers-java · error · IllegalArgumentException

you cannot specify a value smaller than 1 ms

Error message

you cannot specify a value smaller than 1 ms

What it means

HttpWaitStrategy.withReadTimeout(Duration) validates that the per-request HTTP read timeout is at least 1 millisecond. Passing a zero or negative Duration (or one that truncates to <1 ms, like Duration.ofNanos(1)) throws IllegalArgumentException immediately at configuration time.

Solutions

1. Pass a duration of at least 1 millisecond, e.g. Duration.ofSeconds(2).
2. Clamp configured values: `Duration.ofMillis(Math.max(1, configured.toMillis()))`.
3. Check where the Duration is sourced (config file/env) for a zero or negative default.

Example fix

// before
new HttpWaitStrategy().withReadTimeout(Duration.ofMillis(0));
// after
new HttpWaitStrategy().withReadTimeout(Duration.ofSeconds(2));

void safeWithReadTimeout(HttpWaitStrategy s, Duration d) {
  if (d == null || d.isNegative() || d.toMillis() < 1) throw new IllegalArgumentException("read timeout must be >= 1ms");
  s.withReadTimeout(d);
}

boolean isValidReadTimeout(Duration d) { return d != null && !d.isNegative() && d.toMillis() >= 1; }

try { strategy.withReadTimeout(configured); } catch (IllegalArgumentException e) { strategy.withReadTimeout(Duration.ofSeconds(2)); }

When it happens

Trigger: Calling `new HttpWaitStrategy().withReadTimeout(Duration.ZERO)`, `withReadTimeout(Duration.ofMillis(0))`, or any negative/sub-millisecond duration.

Common situations: Configuring timeouts from computed values or external config where a 0 default slips through; typos like ofMillis(-1); unit confusion (nanoseconds vs milliseconds).

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

• Timed out waiting for URL to be accessible
• Timed out waiting for container to become healthy
• Timed out waiting for container port to open ( host ports: …
• HTTP response code was
• Response: did not match predicate

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

Appendix: source

Thrown at core/src/main/java/org/testcontainers/containers/wait/strategy/HttpWaitStrategy.java:192

    /**
     * Add multiple custom HTTP Headers to the call.
     * @param headers Headers map of name/value
     * @return this
     */
    public HttpWaitStrategy withHeaders(Map<String, String> headers) {
        this.headers.putAll(headers);
        return this;
    }

    /**
     * Set the HTTP connections read timeout.
     *
     * @param timeout the timeout (minimum 1 millisecond)
     * @return this
     */
    public HttpWaitStrategy withReadTimeout(Duration timeout) {
        if (timeout.toMillis() < 1) {
            throw new IllegalArgumentException("you cannot specify a value smaller than 1 ms");
        }
        this.readTimeout = timeout;
        return this;
    }

    /**
     * Waits for the response to pass the given predicate
     * @param responsePredicate The predicate to test the response against
     * @return this
     */
    public HttpWaitStrategy forResponsePredicate(Predicate<String> responsePredicate) {
        this.responsePredicate = responsePredicate;
        return this;
    }

    @Override
    protected void waitUntilReady() {
        final String containerName = waitStrategyTarget.getContainerInfo().getName();

View on GitHub (pinned to 8e549514e3)