apache/kafka · warning · IllegalArgumentException

TransactionalId `{transactionalId}` was not included in the

Error message

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

What it means

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).

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 c31c9215e1)

Solutions

1. Pass the exact transactional ID string that you included in the describeTransactions request.
2. Iterate the original requested collection rather than constructing new IDs for lookup.
3. If the ID set changed, issue a new describeTransactions call with the complete list.
4. Validate that the transactional ID is non-null and matches the request (including exact characters).

Example fix

// before
Collection<String> req = List.of("tx-1");
DescribeTransactionsResult r = admin.describeTransactions(req);
r.description("txn-1").get(); // typo, not in request

// after
for (String id : req) {
    r.description(id).get();
}

// Keep the collection of transactional IDs sent to describeTransactions and only
// call description(...) for those.
Collection<String> requestedIds = List.of("tx-1", "tx-2");
DescribeTransactionsResult result = admin.describeTransactions(requestedIds);

String txId = "tx-1";
if (requestedIds.contains(txId)) {
    TransactionDescription d = result.description(txId).get();
} else {
    log.warn("{} not in describeTransactions request", txId);
}

try {
    TransactionDescription d = result.description(txId).get();
} catch (IllegalArgumentException e) {
    // `txId` was not part of the describeTransactions request.
    log.warn("Skipping {}: {}", txId, e.getMessage());
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• TransactionalId `{transactionalId}` was not included in the
• Partition {partition} was not included in the original reque
• Topic {topic} was not included in the original request
• Topic partition {partition} was not included in the request
• Cannot specify a negative version level.

AI-assisted analysis of apache/kafka@c31c9215e1 (2026-08-03). Data as JSON: /data/errors/677d6146da3d1fea.json. Report an issue: GitHub.