[Bug] TopicName and other classes are no longer backward compatible with v4

[TomaszGaweda]

Search before reporting

• I searched in the issues and found nothing similar.

Read release policy

• I understand that unsupported versions don't get bug fixes. I will attempt to reproduce the issue on a supported version of Pulsar client and Pulsar broker.

User environment

Pulsar 5.0.0-M2,

Custom Pulsar connector (not yet published, by Hazelcast).

OpenJDK 21
Using:

<dependency>
                <groupId>org.apache.pulsar</groupId>
                <artifactId>pulsar-bom</artifactId>
                <version>5.0.0-M2</version>
                <scope>import</scope>
                <type>pom</type>
            </dependency>

Issue Description

I've upgraded my pulsar connector to 5.0.0-M2. Maven started complaining:

[ERROR]   symbol:   class NamespaceName
[ERROR]   location: package org.apache.pulsar.common.naming

As I can see, import org.apache.pulsar.common.naming.TopicName; must be replaced with import org.apache.pulsar.shade.org.apache.pulsar.common.naming;

This contradicts "For now, the classic client API remains fully supported, and existing applications keep working unchanged;" from this article

Error messages

hazelcast/extensions/pulsar/src/main/java/com/hazelcast/jet/pulsar/PulsarDataConnection.java:[32,39] cannot find symbol
[ERROR]   symbol:   class NamespaceName
[ERROR]   location: package org.apache.pulsar.common.naming
hazelcast/extensions/pulsar/src/main/java/com/hazelcast/jet/pulsar/PulsarDataConnection.java:[33,39] cannot find symbol
[ERROR]   symbol:   class TopicName
[ERROR]   location: package org.apache.pulsar.common.naming

Reproducing the issue

Have a M1 client that uses TopicName
Upgrade to M2
Compilation errors happen

Additional information

No response

Are you willing to submit a PR?

• I'm willing to submit a PR!

[TomaszGaweda]

Please note, that it is only about pulsar-client library. If I am using "-v5-all", it works fine, so it's not the end of the world, but for sure must be well documented - as just switching versions is not as easy and "existing applications keep working unchanged;" will not be true.

[lhotari]

Please note, that it is only about pulsar-client library. If I am using "-v5-all", it works fine, so it's not the end of the world, but for sure must be well documented - as just switching versions is not as easy and "existing applications keep working unchanged;" will not be true.

Thanks for the feedback. Unfortunately we haven't published the blog post where this is pointed out.
draft:
https://github.com/lhotari/pulsar-site/blob/lh-5.0.0-M2-blog-post/blog/2026-09-17-announcing-apache-pulsar-5-0-m2.md#authentication-tls-and-java-client-dependencies is the draft.
in PR: apache/pulsar-site#1231

https://github.com/apache/pulsar/blob/v5.0.0-M2/pulsar-client-v5-all/README.md is the current reference docs about clients.

Summary: remove all other pulsar-client / pulsar-client-admin dependencies from your dependency tree (also excluding from transitive dependencies) and add pulsar-client-v5-all as the dependency. It also contains the v4 client.

[TomaszGaweda]

Right, I was afraid it's just something overlooked. Make sense with your explanation, thank you @lhotari!