apache/pulsar · error · org.apache.pulsar.client.impl.v5.PulsarClientException

${e.getMessage()}

Error message

${e.getMessage()}

What it means

The synchronous close() delegates to the wrapped v4 client's close(); if the v4 client throws org.apache.pulsar.client.api.PulsarClientException, it is re-thrown as this module's PulsarClientException with the original message and cause. It means graceful shutdown of the client (closing producers/consumers and releasing connections) failed — often due to I/O or already-closed state.

Source

Thrown at pulsar-client-v5/src/main/java/org/apache/pulsar/client/impl/v5/PulsarClientV5.java:106

            throw new PulsarClientException("Interrupted while creating transaction", e);
        }
    }

    @Override
    public CompletableFuture<Transaction> newTransactionAsync() {
        var builder = v4Client.newTransaction();
        if (transactionTimeout != null) {
            builder.withTransactionTimeout(transactionTimeout.toMillis(), TimeUnit.MILLISECONDS);
        }
        return builder.build().thenApply(v4Txn -> (Transaction) new TransactionV5(v4Txn));
    }

    @Override
    public void close() throws PulsarClientException {
        try {
            v4Client.close();
        } catch (org.apache.pulsar.client.api.PulsarClientException e) {
            throw new PulsarClientException(e.getMessage(), e);
        }
    }

    @Override
    public CompletableFuture<Void> closeAsync() {
        return v4Client.closeAsync().exceptionally(ex -> {
            throw new CompletionException(new PulsarClientException(ex.getMessage(), ex));
        });
    }

    @Override
    public void shutdown() {
        try {
            v4Client.shutdown();
        } catch (org.apache.pulsar.client.api.PulsarClientException e) {
            throw new RuntimeException(e);
        }
    }

View on GitHub (pinned to 820761864e)

Solutions

1. Inspect the wrapped cause for the underlying close failure
2. Make cleanup idempotent: track whether the client was already closed to avoid double-close
3. If the cause is network-related, consider calling shutdown() for a forced non-graceful teardown instead

if (clientClosed) return; // guard with your own lifecycle flag

try {
    client.close();
} catch (PulsarClientException e) {
    log.warn("Client close failed: {}", e.getMessage(), e.getCause());
}

When it happens

Trigger: Calling PulsarClientV5.close() when the underlying client fails to shut down cleanly — network errors while closing producers/consumers, or the client was already closed earlier in the lifecycle.

Common situations: Double-close in application cleanup paths (try-with-resources plus manual close); network partitions during shutdown; lingering producers that fail to unsubscribe/close within the close timeout.

Related errors

• Close interrupted
• ${cause}
• Close interrupted
• ${cause}
• ${ex.getMessage()}

AI-assisted analysis of apache/pulsar@820761864e (2026-09-06). Data as JSON: /api/errors/d38558f58217eb6d. Report an issue: GitHub.