{"id":"677d6146da3d1fea","repo":"apache/kafka","slug":"transactionalid-transactionalid-was-not-includ","errorCode":null,"errorMessage":"TransactionalId `{transactionalId}` was not included in the request","messagePattern":"TransactionalId `(.+?)` was not included in the request","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"warning","filePath":"clients/src/main/java/org/apache/kafka/clients/admin/DescribeTransactionsResult.java","lineNumber":50,"sourceCode":"\n    DescribeTransactionsResult(Map<CoordinatorKey, KafkaFuture<TransactionDescription>> futures) {\n        this.futures = futures;\n    }\n\n    /**\n     * Get the description of a specific transactional ID.\n     *\n     * @param transactionalId the transactional ID to describe\n     * @return a future which completes when the transaction description of a particular\n     *         transactional ID is available.\n     * @throws IllegalArgumentException if the `transactionalId` was not included in the\n     *         respective call to {@link Admin#describeTransactions(Collection, DescribeTransactionsOptions)}.\n     */\n    public KafkaFuture<TransactionDescription> description(String transactionalId) {\n        CoordinatorKey key = CoordinatorKey.byTransactionalId(transactionalId);\n        KafkaFuture<TransactionDescription> future = futures.get(key);\n        if (future == null) {\n            throw new IllegalArgumentException(\"TransactionalId \" +\n                \"`\" + transactionalId + \"` was not included in the request\");\n        }\n        return future;\n    }\n    /**\n     * Get a future which returns a map of the transaction descriptions requested in the respective\n     * call to {@link Admin#describeTransactions(Collection, DescribeTransactionsOptions)}.\n     *\n     * If the description fails on any of the transactional IDs in the request, then this future\n     * will also fail.\n     *\n     * @return a future which either completes when all transaction descriptions complete or fails\n     *         if any of the descriptions cannot be obtained\n     */\n    public KafkaFuture<Map<String, TransactionDescription>> all() {\n        return KafkaFuture.allOf(futures.values().toArray(new KafkaFuture<?>[0]))\n            .thenApply(nil -> {\n                Map<String, TransactionDescription> results = new HashMap<>(futures.size());","sourceCodeStart":32,"sourceCodeEnd":68,"githubUrl":"https://github.com/apache/kafka/blob/c31c9215e131f8c17e79f8901b48c13ee6aa8e7a/clients/src/main/java/org/apache/kafka/clients/admin/DescribeTransactionsResult.java#L32-L68","documentation":"Thrown by DescribeTransactionsResult.description when the caller asks for the description of a transactionalId that was not part of the original Admin.describeTransactions request. The result resolves transactional IDs to CoordinatorKey internally; a missing key means the ID was never requested and lookup fails fast with IllegalArgumentException (documented on the method).","triggerScenarios":"Calling result.description(txnId) where txnId was not included in the Collection<String> passed to Admin.describeTransactions. The CoordinatorKey.byTransactionalId lookup will not match any key in the futures map, so future == null triggers the exception.","commonSituations":"Caller requests a fixed list of transactional IDs but queries a different one (typo, stale config, env mismatch); transactional IDs generated dynamically for lookup but static for the request; refactoring that introduced new IDs without updating the request; cross-thread sharing of a result object.","solutions":["Pass the exact transactional ID string that you included in the describeTransactions request.","Iterate the original requested collection rather than constructing new IDs for lookup.","If the ID set changed, issue a new describeTransactions call with the complete list.","Validate that the transactional ID is non-null and matches the request (including exact characters)."],"exampleFix":"// before\nCollection<String> req = List.of(\"tx-1\");\nDescribeTransactionsResult r = admin.describeTransactions(req);\nr.description(\"txn-1\").get(); // typo, not in request\n\n// after\nfor (String id : req) {\n    r.description(id).get();\n}","handlingStrategy":"validation","validationCode":"// Keep the collection of transactional IDs sent to describeTransactions and only\n// call description(...) for those.\nCollection<String> requestedIds = List.of(\"tx-1\", \"tx-2\");\nDescribeTransactionsResult result = admin.describeTransactions(requestedIds);\n\nString txId = \"tx-1\";\nif (requestedIds.contains(txId)) {\n    TransactionDescription d = result.description(txId).get();\n} else {\n    log.warn(\"{} not in describeTransactions request\", txId);\n}","typeGuard":null,"tryCatchPattern":"try {\n    TransactionDescription d = result.description(txId).get();\n} catch (IllegalArgumentException e) {\n    // `txId` was not part of the describeTransactions request.\n    log.warn(\"Skipping {}: {}\", txId, e.getMessage());\n}","preventionTips":["Iterate over the same Collection<String> passed to Admin.describeTransactions when collecting per-id results.","Use result.all() for bulk consumption; it cannot throw the not-included error.","Normalize transactional IDs (trim, consistent casing) before both the request and the lookup.","Do not mix transactional IDs sourced from a different store than the request collection."],"tags":["admin-client","transactions","api-misuse","illegal-argument","request-set"],"analyzedSha":"c31c9215e131f8c17e79f8901b48c13ee6aa8e7a","analyzedAt":"2026-08-03T12:34:05.770Z","schemaVersion":2}