apache/pulsar · warning · BrokerFilterBadVersionException

Invalid version string in lookup data for broker "${brokerId

Error message

Invalid version string in lookup data for broker "${brokerId}": "${version}")

What it means

getLatestVersionNumber parses each broker's version string with Version.valueOf (SemVer). If a broker reports a string that is not valid SemVer (e.g. '3.2.0-SNAPSHOT-with-suffix', 'unknown', 'custom-build'), parsing fails and a BrokerFilterBadVersionException is thrown quoting the bad version, disabling PreferLaterVersions.

Source

Thrown at pulsar-broker/src/main/java/org/apache/pulsar/broker/loadbalance/extensions/filter/BrokerVersionFilter.java:134

        for (Map.Entry<String, BrokerLookupData> entry : brokerMap.entrySet()) {
            String brokerId = entry.getKey();
            String version = entry.getValue().brokerVersion();
            if (null == version || version.length() == 0) {
                log.warn().attr("broker", brokerId)
                        .log("No version string in lookup data for broker; disabling PreferLaterVersions feature");
                // Trigger the load manager to reset all the brokers to the original set
                throw new BrokerFilterBadVersionException("No version string in lookup data for broker \""
                        + brokerId + "\"");
            }
            Version brokerVersionVersion;
            try {
                brokerVersionVersion = Version.valueOf(version);
            } catch (Exception x) {
                log.warn().attr("broker", brokerId).attr("version", version)
                        .log("Invalid version string in lookup data for broker;"
                                + " disabling PreferLaterVersions feature");
                // Trigger the load manager to reset all the brokers to the original set
                throw new BrokerFilterBadVersionException("Invalid version string in lookup data for broker \""
                        + brokerId + "\": \"" + version + "\")");
            }

            if (latestVersion == null) {
                latestVersion = brokerVersionVersion;
            } else if (Version.BUILD_AWARE_ORDER.compare(latestVersion, brokerVersionVersion) < 0) {
                latestVersion = brokerVersionVersion;
            }
        }

        return latestVersion;
    }

    @Override
    public String name() {
        return FILTER_NAME;
    }
}

View on GitHub (pinned to 820761864e)

Solutions

Rebuild/deploy the offending broker with a valid SemVer version string (MAJOR.MINOR.PATCH).
Identify the broker named in the message and check its reported version via its /admin/v2/broker-status or lookup data.
Disable preferLaterVersions or remove broker_version_filter until all brokers report valid versions.
In tests, always set a parseable version like "3.2.1" on BrokerLookupData.

Example fix

// before
String version = "3.2.0-custom-build"; // not parseable
// after
String version = "3.2.0"; // valid SemVer; put build info elsewhere

Defensive patterns

Strategy: validation

Validate before calling

try {
    Version.valueOf(broker.getBrokerVersion());
} catch (Exception e) {
    throw new IllegalStateException("Non-semver version on " + brokerId + ": " + broker.getBrokerVersion());
}

Type guard

boolean isSemver(String v) {
    if (v == null) return false;
    try { Version.valueOf(v); return true; } catch (Exception e) { return false; }
}

Try / catch

try {
    latest = filter.getLatestVersionNumber(brokerMap);
} catch (BrokerFilterBadVersionException e) {
    log.warn("Bad version in lookup data, filter disabled: {}", e.getMessage());
}

Prevention

Standardize on SemVer MAJOR.MINOR.PATCH broker versions; keep build metadata as separate SemVer build labels if needed.
Validate reported broker version at broker startup with Version.valueOf.
After custom builds, verify the version via the broker's health/admin endpoint before joining the cluster.

When it happens

Trigger: Any broker in the candidate map publishes a brokerVersion() string that Version.valueOf cannot parse (null handled separately at error 261; this is the non-empty-but-unparseable case).

Common situations: Custom/forked broker builds with non-semver version strings, snapshot builds, a build that overrode the project version, or hand-edited lookup data in tests.

Related errors

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