{"id":"123552f1ea32e8fe","repo":"apache/kafka","slug":"the-specified-value-of-default-api-timeout-ms-must","errorCode":null,"errorMessage":"The specified value of default.api.timeout.ms must be no smaller than the value of request.timeout.ms.","messagePattern":"The specified value of default\\.api\\.timeout\\.ms must be no smaller than the value of request\\.timeout\\.ms\\.","errorType":"validation","errorClass":"ConfigException","httpStatus":null,"severity":"error","filePath":"clients/src/main/java/org/apache/kafka/clients/admin/KafkaAdminClient.java","lineNumber":707,"sourceCode":"        AppInfoParser.registerAppInfo(JMX_PREFIX, clientId, metrics, time.milliseconds());\n        log.debug(\"Kafka admin client initialized\");\n        thread.start();\n    }\n\n    /**\n     * If a default.api.timeout.ms has been explicitly specified, raise an error if it conflicts with request.timeout.ms.\n     * 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.\n     * Otherwise, use the provided values for both configurations.\n     *\n     * @param config The configuration\n     */\n    private int configureDefaultApiTimeoutMs(AdminClientConfig config) {\n        int requestTimeoutMs = config.getInt(AdminClientConfig.REQUEST_TIMEOUT_MS_CONFIG);\n        int defaultApiTimeoutMs = config.getInt(AdminClientConfig.DEFAULT_API_TIMEOUT_MS_CONFIG);\n\n        if (defaultApiTimeoutMs < requestTimeoutMs) {\n            if (config.originals().containsKey(AdminClientConfig.DEFAULT_API_TIMEOUT_MS_CONFIG)) {\n                throw new ConfigException(\"The specified value of \" + AdminClientConfig.DEFAULT_API_TIMEOUT_MS_CONFIG +\n                    \" must be no smaller than the value of \" + AdminClientConfig.REQUEST_TIMEOUT_MS_CONFIG + \".\");\n            } else {\n                log.warn(\"Overriding the default value for {} ({}) with the explicitly configured request timeout {}\",\n                    AdminClientConfig.DEFAULT_API_TIMEOUT_MS_CONFIG, defaultApiTimeoutMs,\n                    requestTimeoutMs);\n                return requestTimeoutMs;\n            }\n        }\n        return defaultApiTimeoutMs;\n    }\n\n    @Override\n    public void close(Duration timeout) {\n        long waitTimeMs = timeout.toMillis();\n        if (waitTimeMs < 0)\n            throw new IllegalArgumentException(\"The timeout cannot be negative.\");\n        waitTimeMs = Math.min(TimeUnit.DAYS.toMillis(365), waitTimeMs); // Limit the timeout to a year.\n        long now = time.milliseconds();","sourceCodeStart":689,"sourceCodeEnd":725,"githubUrl":"https://github.com/apache/kafka/blob/c31c9215e131f8c17e79f8901b48c13ee6aa8e7a/clients/src/main/java/org/apache/kafka/clients/admin/KafkaAdminClient.java#L689-L725","documentation":"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).","triggerScenarios":"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.","commonSituations":"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.","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)."],"exampleFix":"// before\nprops.put(AdminClientConfig.REQUEST_TIMEOUT_MS_CONFIG, 30000);\nprops.put(AdminClientConfig.DEFAULT_API_TIMEOUT_MS_CONFIG, 10000); // < request timeout -> throws\nAdmin admin = Admin.create(props);\n\n// after\nprops.put(AdminClientConfig.REQUEST_TIMEOUT_MS_CONFIG, 30000);\nprops.put(AdminClientConfig.DEFAULT_API_TIMEOUT_MS_CONFIG, 60000); // >= request timeout\nAdmin admin = Admin.create(props);","handlingStrategy":"validation","validationCode":"int requestTimeoutMs = Integer.parseInt(\n    String.valueOf(props.getOrDefault(AdminClientConfig.REQUEST_TIMEOUT_MS_CONFIG, \"30000\")));\nint defaultApiTimeoutMs = Integer.parseInt(\n    String.valueOf(props.getOrDefault(AdminClientConfig.DEFAULT_API_TIMEOUT_MS_CONFIG, \"60000\")));\nif (defaultApiTimeoutMs < requestTimeoutMs) {\n    throw new IllegalArgumentException(\n        \"default.api.timeout.ms (\" + defaultApiTimeoutMs\n        + \") must be >= request.timeout.ms (\" + requestTimeoutMs + \")\");\n}","typeGuard":null,"tryCatchPattern":"try {\n    Admin admin = Admin.create(props);\n} catch (ConfigException e) {\n    // timeout ordering violation\n    log.error(\"Timeout config invalid\", e);\n}","preventionTips":["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."],"tags":["configuration","admin-client","timeout","startup"],"analyzedSha":"c31c9215e131f8c17e79f8901b48c13ee6aa8e7a","analyzedAt":"2026-08-03T12:34:05.770Z","schemaVersion":2}