apache/kafka · error · ConfigException

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

Error message

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

What it means

A ConfigException thrown by KafkaAdminClient.configureDefaultApiTimeoutMs when the user explicitly set default.api.timeout.ms to a value smaller than request.timeout.ms. The default API timeout must be at least as large as the per-request timeout, otherwise individual requests could outlive the overall operation timeout.

Solutions

Set default.api.timeout.ms to a value >= request.timeout.ms.
If you only need to tune request.timeout.ms, either leave default.api.timeout.ms unset (the client will auto-bump it) or raise it to match.
Centralize timeout config so the two values are derived from one source with the correct ordering.

Example fix

// before
props.put("request.timeout.ms", 90000);
props.put("default.api.timeout.ms", 60000);

// after
props.put("request.timeout.ms", 90000);
props.put("default.api.timeout.ms", 120000);

Defensive patterns

Strategy: validation

Validate before calling

int reqTimeout = Integer.parseInt(props.getProperty("request.timeout.ms", "30000"));
int defApiTimeout = Integer.parseInt(props.getProperty("default.api.timeout.ms", "60000"));
if (defApiTimeout < reqTimeout) {
    props.setProperty("default.api.timeout.ms", Integer.toString(reqTimeout));
}

Try / catch

try {
    Admin.create(props);
} catch (ConfigException e) {
    if (e.getMessage().contains("default.api.timeout.ms")) {
        props.setProperty("default.api.timeout.ms", props.getProperty("request.timeout.ms"));
        Admin.create(props);
    }
}

Prevention

Derive default.api.timeout.ms from request.timeout.ms in a single config builder so the ordering is guaranteed.
When tuning one timeout up, audit the other.

When it happens

Trigger: Configuration where default.api.timeout.ms < request.timeout.ms AND the user explicitly provided default.api.timeout.ms (it appears in originals()). Common when tuning request.timeout.ms up for slow networks without adjusting the default API timeout.

Common situations: Hardening request timeouts for a slow link (raising request.timeout.ms to 60s) while leaving default.api.timeout.ms at its 60s default, then raising request timeout further; copying values between environments without rechecking the relationship.

Understand the failure class

Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

Related errors

AI-assisted analysis of apache/kafka@996fb4585a (2026-08-11). Data as JSON: /api/errors/123552f1ea32e8fe. Report an issue: GitHub.

Appendix: source

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

        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 996fb4585a)