{"record":{"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":710,"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":692,"sourceCodeEnd":728,"githubUrl":"https://github.com/apache/kafka/blob/996fb4585aa1bcc8980b0e1b8d6b168b986cd979/clients/src/main/java/org/apache/kafka/clients/admin/KafkaAdminClient.java#L692-L728","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"// before\nprops.put(\"request.timeout.ms\", 90000);\nprops.put(\"default.api.timeout.ms\", 60000);\n\n// after\nprops.put(\"request.timeout.ms\", 90000);\nprops.put(\"default.api.timeout.ms\", 120000);","handlingStrategy":"validation","validationCode":"int reqTimeout = Integer.parseInt(props.getProperty(\"request.timeout.ms\", \"30000\"));\nint defApiTimeout = Integer.parseInt(props.getProperty(\"default.api.timeout.ms\", \"60000\"));\nif (defApiTimeout < reqTimeout) {\n    props.setProperty(\"default.api.timeout.ms\", Integer.toString(reqTimeout));\n}","typeGuard":null,"tryCatchPattern":"try {\n    Admin.create(props);\n} catch (ConfigException e) {\n    if (e.getMessage().contains(\"default.api.timeout.ms\")) {\n        props.setProperty(\"default.api.timeout.ms\", props.getProperty(\"request.timeout.ms\"));\n        Admin.create(props);\n    }\n}","preventionTips":["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."],"tags":["kafka-admin","configuration","timeout","client-setup"],"backgroundTag":null,"analyzedSha":"996fb4585aa1bcc8980b0e1b8d6b168b986cd979","analyzedAt":"2026-08-11T22:03:28.655Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}