{"record":{"id":"911e0a2b4a681b80","repo":"apache/pulsar","slug":"cannot-load-pulsar-client-implementation","errorCode":null,"errorMessage":"Cannot load Pulsar Client Implementation: ","messagePattern":"Cannot load Pulsar Client Implementation: ","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"critical","filePath":"pulsar-client-api/src/main/java/org/apache/pulsar/client/internal/DefaultImplementation.java","lineNumber":36,"sourceCode":" */\npackage org.apache.pulsar.client.internal;\n\n/**\n * This class loads the implementation for {@link PulsarClientImplementationBinding}\n * and allows you to decouple the API from the actual implementation.\n * <b>This class is internal to the Pulsar API implementation, and it is not part of the public API\n * it is not meant to be used by client applications.</b>\n */\npublic class DefaultImplementation {\n    private static final PulsarClientImplementationBinding IMPLEMENTATION;\n    static {\n        PulsarClientImplementationBinding impl;\n        try {\n            impl = (PulsarClientImplementationBinding) ReflectionUtils\n                    .newClassInstance(\"org.apache.pulsar.client.impl.PulsarClientImplementationBindingImpl\")\n                    .getConstructor().newInstance();\n        } catch (Throwable error) {\n            throw new RuntimeException(\"Cannot load Pulsar Client Implementation: \" + error, error);\n        }\n        IMPLEMENTATION = impl;\n    }\n\n    /**\n     * Access the actual implementation of the Pulsar Client API.\n     * @return the loaded implementation.\n     */\n    public static PulsarClientImplementationBinding getDefaultImplementation() {\n        return IMPLEMENTATION;\n    }\n\n}\n","sourceCodeStart":18,"sourceCodeEnd":50,"githubUrl":"https://github.com/apache/pulsar/blob/820761864ed8e2a7d2e52dd9763ad2ae117c1395/pulsar-client-api/src/main/java/org/apache/pulsar/client/internal/DefaultImplementation.java#L18-L50","documentation":"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.","triggerScenarios":"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.**.","commonSituations":"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.","solutions":["Add the implementation dependency at the exact same version as the API, e.g. org.apache.pulsar:pulsar-client:<version>.","Read the wrapped cause in the exception message to distinguish missing class vs. initialization failure, and fix the corresponding jar.","Align all pulsar-* artifact versions (BOM: pulsar-bom) so api and impl cannot drift.","Inspect the packaged jar (or shadowJar contents) to confirm org/apache/pulsar/client/impl/PulsarClientImplementationBindingImpl.class is present."],"exampleFix":"// before (build.gradle)\nimplementation 'org.apache.pulsar:pulsar-client-api:3.0.0'\n// after\nimplementation 'org.apache.pulsar:pulsar-client:3.0.0' // pulls in pulsar-client-api transitively","handlingStrategy":"try-catch","validationCode":"static void verifyPulsarImplementationOnClasspath() {\n    try {\n        Class.forName(\"org.apache.pulsar.client.impl.PulsarClientImplementationBindingImpl\");\n    } catch (ClassNotFoundException e) {\n        throw new IllegalStateException(\"Add org.apache.pulsar:pulsar-client to the runtime classpath\", e);\n    }\n}\n// run at startup, before creating a client","typeGuard":null,"tryCatchPattern":"try {\n    PulsarClient client = PulsarClient.builder().serviceUrl(url).create();\n} catch (RuntimeException e) {\n    if (e.getMessage() != null && e.getMessage().startsWith(\"Cannot load Pulsar Client Implementation:\")) {\n        // classpath problem: add/align the pulsar-client artifact; log e.getCause()\n    } else throw e;\n}","preventionTips":["Depend on org.apache.pulsar:pulsar-client (not just pulsar-client-api) at the same version.","Use pulsar-bom to keep all pulsar-* versions aligned.","Check shadow/proguard/minify configs keep org.apache.pulsar.client.impl.**.","Fail fast with a startup Class.forName probe so the misconfiguration surfaces before first produce."],"tags":["classpath","reflection","dependency-missing","startup"],"backgroundTag":"classpath-missing-implementation","analyzedSha":"820761864ed8e2a7d2e52dd9763ad2ae117c1395","analyzedAt":"2026-09-06T00:14:20.138Z","contentChangedAt":"2026-09-06T00:14:20.138Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}