apache/kafka · error · ConfigException

The specified value of default.api.timeout.ms must be no sma

Error message

The specified value of default.api.timeout.ms must be no smaller than the value of request.timeout.ms.

What it means

Thrown by KafkaAdminClient.configureDefaultApiTimeoutMs when default.api.timeout.ms is explicitly configured to a value smaller than request.timeout.ms. The default api timeout is the upper bound for an entire retried operation while request.timeout.ms bounds a single network request, so a default smaller than the per-request timeout is logically inconsistent and would make retries impossible; the client rejects it only when the user explicitly set default.api.timeout.ms (otherwise it silently overrides the default upward and logs a warning).

Source

Thrown at clients/src/main/java/org/apache/kafka/clients/admin/KafkaAdminClient.java:707

        AppInfoParser.registerAppInfo(JMX_PREFIX, clientId, metrics, time.milliseconds());
        log.debug("Kafka admin client initialized");
        thread.start();
    }

    /**
     * If a default.api.timeout.ms has been explicitly specified, raise an error if it conflicts with request.timeout.ms.
     * If no default.api.timeout.ms has been configured, then set its value as the max of the default and request.timeout.ms. Also we should probably log a warning.
     * Otherwise, use the provided values for both configurations.
     *
     * @param config The configuration
     */
    private int configureDefaultApiTimeoutMs(AdminClientConfig config) {
        int requestTimeoutMs = config.getInt(AdminClientConfig.REQUEST_TIMEOUT_MS_CONFIG);
        int defaultApiTimeoutMs = config.getInt(AdminClientConfig.DEFAULT_API_TIMEOUT_MS_CONFIG);

        if (defaultApiTimeoutMs < requestTimeoutMs) {
            if (config.originals().containsKey(AdminClientConfig.DEFAULT_API_TIMEOUT_MS_CONFIG)) {
                throw new ConfigException("The specified value of " + AdminClientConfig.DEFAULT_API_TIMEOUT_MS_CONFIG +
                    " must be no smaller than the value of " + AdminClientConfig.REQUEST_TIMEOUT_MS_CONFIG + ".");
            } else {
                log.warn("Overriding the default value for {} ({}) with the explicitly configured request timeout {}",
                    AdminClientConfig.DEFAULT_API_TIMEOUT_MS_CONFIG, defaultApiTimeoutMs,
                    requestTimeoutMs);
                return requestTimeoutMs;
            }
        }
        return defaultApiTimeoutMs;
    }

    @Override
    public void close(Duration timeout) {
        long waitTimeMs = timeout.toMillis();
        if (waitTimeMs < 0)
            throw new IllegalArgumentException("The timeout cannot be negative.");
        waitTimeMs = Math.min(TimeUnit.DAYS.toMillis(365), waitTimeMs); // Limit the timeout to a year.
        long now = time.milliseconds();

View on GitHub (pinned to c31c9215e1)

Solutions

Set default.api.timeout.ms to a value >= request.timeout.ms (preferred: leave default.api.timeout.ms unset and only tune request.timeout.ms).
If you intentionally want a short overall timeout, lower request.timeout.ms first, then set default.api.timeout.ms to the same or a larger value.
Remove the explicit default.api.timeout.ms override entirely so the client auto-adjusts the default to be >= request.timeout.ms (with a warn log).

Example fix

// before
props.put(AdminClientConfig.REQUEST_TIMEOUT_MS_CONFIG, 30000);
props.put(AdminClientConfig.DEFAULT_API_TIMEOUT_MS_CONFIG, 10000); // < request timeout -> throws
Admin admin = Admin.create(props);

// after
props.put(AdminClientConfig.REQUEST_TIMEOUT_MS_CONFIG, 30000);
props.put(AdminClientConfig.DEFAULT_API_TIMEOUT_MS_CONFIG, 60000); // >= request timeout
Admin admin = Admin.create(props);

Defensive patterns

Strategy: validation

Validate before calling

int requestTimeoutMs = Integer.parseInt(
    String.valueOf(props.getOrDefault(AdminClientConfig.REQUEST_TIMEOUT_MS_CONFIG, "30000")));
int defaultApiTimeoutMs = Integer.parseInt(
    String.valueOf(props.getOrDefault(AdminClientConfig.DEFAULT_API_TIMEOUT_MS_CONFIG, "60000")));
if (defaultApiTimeoutMs < requestTimeoutMs) {
    throw new IllegalArgumentException(
        "default.api.timeout.ms (" + defaultApiTimeoutMs
        + ") must be >= request.timeout.ms (" + requestTimeoutMs + ")");
}

Try / catch

try {
    Admin admin = Admin.create(props);
} catch (ConfigException e) {
    // timeout ordering violation
    log.error("Timeout config invalid", e);
}

Prevention

Only set request.timeout.ms explicitly; leave default.api.timeout.ms at its default (>= request timeout) unless you need a longer overall cap.
If you tune both, keep the invariant default.api.timeout.ms >= request.timeout.ms in your config template.
Avoid copying producer/consumer timeout settings into Admin configs verbatim — their defaults differ.

When it happens

Trigger: Admin config with AdminClientConfig.DEFAULT_API_TIMEOUT_MS_CONFIG explicitly set to an integer smaller than AdminClientConfig.REQUEST_TIMEOUT_MS_CONFIG (e.g. request.timeout.ms=30000, default.api.timeout.ms=10000). The check fires in the KafkaAdminClient constructor path via configureDefaultApiTimeoutMs.

Common situations: Tightening timeouts during incident tuning where someone lowered default.api.timeout.ms but left a larger request.timeout.ms; copy-pasting two values from different examples; Spring config where default.api.timeout.ms and request.timeout.ms come from different property sources and one wasn't updated.

Related errors

AI-assisted analysis of apache/kafka@c31c9215e1 (2026-08-03). Data as JSON: /data/errors/123552f1ea32e8fe.json. Report an issue: GitHub.