Has anyone encountered breaking changes or disruptions when upgrading from Pulsar 4.x to 5.x?

[Rutuja-IBM]

We're currently evaluating an upgrade of our production environment from Apache Pulsar 4.x to 5.x and are trying to identify any potential risks before proceeding.

I'd like to hear from anyone who has already completed (or attempted) this upgrade.
Specifically, I'm interested in:

1. Did you encounter any breaking changes or unexpected disruptions during the upgrade?
2. Were there any deprecated or removed APIs/configurations that required code or configuration changes?
3. Did you face any issues with brokers, proxies, Functions, connectors, or metadata storage?
4. Were there any client compatibility issues (Java, Go, Python, Node.js, etc.) with existing applications?
5. Any surprises around Helm charts, broker configuration, or operational behavior?
6. Are there any lessons learned or recommendations you'd share for a smoother upgrade?

Any experiences, migration tips, or references to useful documentation would be greatly appreciated.
Thanks in advance!

[lMysticl]

Update — 20 October 2026: the release-status part of my July answer is outdated. Pulsar 5.0.0 was published on 5 October as a non-prerelease, after M1 and M2. Assess a 4.x → 5.0 migration against the GA release notes and upgrade guidance for your exact source version.

The GA notes include both milestone change sets. The milestone notes identified these migration areas:

• broker plugins, interceptors, authentication/authorization providers and other extensions using javax.* need assessment for the move to jakarta.*;
• the removed Etcd metadata-store backend requires a migration plan for affected deployments;
• Pulsar IO connectors have a separate repository and release cycle;
• source builds moved from Maven to Gradle, while published Maven artifacts and Docker images remain available;
• the v5 client API is additive; moving the broker does not by itself require every application to adopt it;
• verify the chosen metadata-store and ZooKeeper/Oxia configuration against the GA documentation.

Those are inventory items, not a compatibility guarantee. Test your actual Functions, connectors, broker extensions, Helm values, authentication providers, and rolling broker/client upgrade path in staging.

The previous “only M1 is available” objection no longer applies. The earlier milestone details remain available in the M1 notes; the 5.0.0 GA notes are now the release reference.