apache/pulsar · critical · RuntimeException

Cannot load Pulsar Client Implementation:

Error message

Cannot load Pulsar Client Implementation: 

What it means

DefaultImplementation's static initializer reflectively instantiates org.apache.pulsar.client.impl.PulsarClientImplementationBindingImpl and wraps any failure (ClassNotFoundException, linkage errors, constructor failures) in a RuntimeException with the prefix 'Cannot load Pulsar Client Implementation: '. The pulsar-client-api jar is only an API surface; the actual implementation lives in a separate artifact that must be on the classpath.

Source

Thrown at pulsar-client-api/src/main/java/org/apache/pulsar/client/internal/DefaultImplementation.java:36

 */
package org.apache.pulsar.client.internal;

/**
 * This class loads the implementation for {@link PulsarClientImplementationBinding}
 * and allows you to decouple the API from the actual implementation.
 * <b>This class is internal to the Pulsar API implementation, and it is not part of the public API
 * it is not meant to be used by client applications.</b>
 */
public class DefaultImplementation {
    private static final PulsarClientImplementationBinding IMPLEMENTATION;
    static {
        PulsarClientImplementationBinding impl;
        try {
            impl = (PulsarClientImplementationBinding) ReflectionUtils
                    .newClassInstance("org.apache.pulsar.client.impl.PulsarClientImplementationBindingImpl")
                    .getConstructor().newInstance();
        } catch (Throwable error) {
            throw new RuntimeException("Cannot load Pulsar Client Implementation: " + error, error);
        }
        IMPLEMENTATION = impl;
    }

    /**
     * Access the actual implementation of the Pulsar Client API.
     * @return the loaded implementation.
     */
    public static PulsarClientImplementationBinding getDefaultImplementation() {
        return IMPLEMENTATION;
    }

}

View on GitHub (pinned to 820761864e)

Solutions

1. Add the implementation dependency at the exact same version as the API, e.g. org.apache.pulsar:pulsar-client:<version>.
2. Read the wrapped cause in the exception message to distinguish missing class vs. initialization failure, and fix the corresponding jar.
3. Align all pulsar-* artifact versions (BOM: pulsar-bom) so api and impl cannot drift.
4. Inspect the packaged jar (or shadowJar contents) to confirm org/apache/pulsar/client/impl/PulsarClientImplementationBindingImpl.class is present.

Example fix

// before (build.gradle)
implementation 'org.apache.pulsar:pulsar-client-api:3.0.0'
// after
implementation 'org.apache.pulsar:pulsar-client:3.0.0' // pulls in pulsar-client-api transitively

static void verifyPulsarImplementationOnClasspath() {
    try {
        Class.forName("org.apache.pulsar.client.impl.PulsarClientImplementationBindingImpl");
    } catch (ClassNotFoundException e) {
        throw new IllegalStateException("Add org.apache.pulsar:pulsar-client to the runtime classpath", e);
    }
}
// run at startup, before creating a client

try {
    PulsarClient client = PulsarClient.builder().serviceUrl(url).create();
} catch (RuntimeException e) {
    if (e.getMessage() != null && e.getMessage().startsWith("Cannot load Pulsar Client Implementation:")) {
        // classpath problem: add/align the pulsar-client artifact; log e.getCause()
    } else throw e;
}

When it happens

Trigger: Loading PulsarClient/DefaultImplementation when the pulsar-client (implementation) jar is absent from the runtime classpath; a version mismatch between pulsar-client-api and pulsar-client so the binding class exists but fails to initialize; shaded/fat-jar builds that excluded org.apache.pulsar.client.impl.**.

Common situations: Adding only pulsar-client-api to a Gradle/Maven project; ProGuard/minify or Spring Boot thin layouts stripping impl classes; mixing pulsar-client 2.x with pulsar-client-api 3.x/4.x after the api/impl split; NoClassDefFoundError shown as the wrapped cause.

Related errors

• Failed to load an authorization provider.
• (wraps ClassNotFoundException for BrokerEntryMetadataInterce
• (wraps ClassNotFoundException for interceptor)
• User class must be in class path
• function kind %s is not %s

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