apache/kafka · error · IllegalArgumentException

TransactionalId ` ` was not included in the request

Error message

TransactionalId `{transactionalId}` was not included in the request

What it means

Thrown by DescribeTransactionsResult.description() when the given transactionalId maps to a CoordinatorKey that has no entry in the futures map — meaning that transactional ID was not included in the original Admin.describeTransactions request. The message wraps the transactionalId in backticks for clarity.

Solutions

1. Only call description(id) with transactional IDs that were in the original describeTransactions request.
2. Keep the original collection of IDs and verify membership before lookup.
3. Normalize/trim the ID string to avoid subtle mismatches.
4. Use the all() future to get every requested result without per-ID lookup.

Example fix

// before
result.description(txnId);

// after
if (requestedTxnIds.contains(txnId)) {
    result.description(txnId);
}

Set<String> requestedTxnIds = ...;
if (!requestedTxnIds.contains(transactionalId)) {
    throw new IllegalArgumentException(transactionalId + " not in original request");
}
result.description(transactionalId);

boolean wasRequested(Set<String> requested, String txnId) {
    return requested.contains(txnId);
}

When it happens

Trigger: Calling description(transactionalId) where futures.get(CoordinatorKey.byTransactionalId(transactionalId)) returns null. The ID was not among those passed to describeTransactions.

Common situations: Caller queries a transactional ID not in the original request set, or the ID differs by whitespace/case/encoding from what was requested.

Related errors

• Partition was not included in the original request
• Topic partition was not included in the request
• Topic was not included in the original request
• topicIdFutures and nameFutures cannot both be null.
• topicIdFutures and nameFutures cannot both be null.

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

Appendix: source

Thrown at clients/src/main/java/org/apache/kafka/clients/admin/DescribeTransactionsResult.java:50

    DescribeTransactionsResult(Map<CoordinatorKey, KafkaFuture<TransactionDescription>> futures) {
        this.futures = futures;
    }

    /**
     * Get the description of a specific transactional ID.
     *
     * @param transactionalId the transactional ID to describe
     * @return a future which completes when the transaction description of a particular
     *         transactional ID is available.
     * @throws IllegalArgumentException if the `transactionalId` was not included in the
     *         respective call to {@link Admin#describeTransactions(Collection, DescribeTransactionsOptions)}.
     */
    public KafkaFuture<TransactionDescription> description(String transactionalId) {
        CoordinatorKey key = CoordinatorKey.byTransactionalId(transactionalId);
        KafkaFuture<TransactionDescription> future = futures.get(key);
        if (future == null) {
            throw new IllegalArgumentException("TransactionalId " +
                "`" + transactionalId + "` was not included in the request");
        }
        return future;
    }
    /**
     * Get a future which returns a map of the transaction descriptions requested in the respective
     * call to {@link Admin#describeTransactions(Collection, DescribeTransactionsOptions)}.
     *
     * If the description fails on any of the transactional IDs in the request, then this future
     * will also fail.
     *
     * @return a future which either completes when all transaction descriptions complete or fails
     *         if any of the descriptions cannot be obtained
     */
    public KafkaFuture<Map<String, TransactionDescription>> all() {
        return KafkaFuture.allOf(futures.values().toArray(new KafkaFuture<?>[0]))
            .thenApply(nil -> {
                Map<String, TransactionDescription> results = new HashMap<>(futures.size());

View on GitHub (pinned to 996fb4585a)