pinpoint-apm/pinpoint · critical · HBaseAccessException

HBase version compatibility violation HBaseClient:%s, HBaseS

Error message

HBase version compatibility violation HBaseClient:%s, HBaseServer:%s

What it means

Thrown during HbaseVersionCheckBean.afterPropertiesSet when the client's HBase version is not accepted by the server version policy. Pinpoint wires this bean at Spring context startup to fail fast on incompatible client/server HBase combinations, since an incompatible server breaks writes/reads in unpredictable ways.

Source

Thrown at commons-hbase/src/main/java/com/navercorp/pinpoint/common/hbase/HbaseVersionCheckBean.java:58

        this.hbaseVersionCompatibility = hbaseVersionCompatibility;
    }

    @Override
    public void afterPropertiesSet() throws Exception {
        ClusterMetrics clusterMetrics = template.execute(Admin::getClusterMetrics);
        logger.info("HBase ClusterMetrics:{}", clusterMetrics);

        String hBaseServerVersion = clusterMetrics.getHBaseVersion();
        logger.info("HBaseServerVersion:{}", hBaseServerVersion);
        if (!hbaseVersionCompatibility) {
            return;
        }

        HBaseClientVersion hbaseClientVersion = getHbaseClientVersion();
        if (!hbaseClientVersion.acceptVersion(hBaseServerVersion)) {
            String error = String.format("HBase version compatibility violation HBaseClient:%s, HBaseServer:%s", hbaseClientVersion, hBaseServerVersion);
            logger.error(error);
            throw new HBaseAccessException(error);
        }

    }

    private HBaseClientVersion getHbaseClientVersion() {
        final String version = VersionInfo.getVersion();
        logger.info("HBaseClientVersion:{}", version);

        HBaseClientVersion hBaseClientVersion = HBaseClientVersion.getHBaseVersion(version);
        if (hBaseClientVersion == null) {
            throw new HBaseAccessException("Unknown HbaseClientVersion:" + version);
        }
        return hBaseClientVersion;
    }
}

View on GitHub (pinned to 744c3d3075)

Solutions

1. Compare the logged client and server versions in the error message and align the HBase server with a version supported by this pinpoint build (or vice versa)
2. Update the hbase.client.version / hbase.server.version configuration properties to versions on the compatibility matrix for your pinpoint version
3. Upgrade pinpoint commons-hbase/web/collector to a release that supports your HBase server version
4. If intentionally bypassing, check whether the bean exposes a version-check disable flag in your pinpoint version before disabling it

Example fix

// before
hbase.clientVersion=2.4
hbase.serverVersion=1.2
// after
hbase.clientVersion=2.4
hbase.serverVersion=2.4

String clientV = VersionInfo.getVersion();
HBaseClientVersion cv = HBaseClientVersion.getHBaseVersion(clientV);
if (cv == null || !cv.acceptVersion(hBaseServerVersion)) {
    throw new IllegalStateException("Unsupported HBase client/server combination: " + clientV + " vs " + hBaseServerVersion);
}

try {
    applicationContext.refresh(); // or bean init
} catch (HBaseAccessException e) {
    logger.fatal("HBase version mismatch: {}", e.getMessage());
    System.exit(1); // fail fast; do not run with incompatible HBase
}

When it happens

Trigger: Spring context initialization of HbaseVersionCheckBean when HBaseClientVersion.acceptVersion(hBaseServerVersion) returns false for the resolved client version (VersionInfo.getVersion()) versus the configured hBaseServerVersion.

Common situations: Upgrading or downgrading the HBase server cluster without updating the pinpoint client's hBaseClientVersion/hBaseServerVersion config; pointing a newer pinpoint web/collector at an older HBase 1.x cluster; custom HBase builds reporting unrecognized version strings.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

• Unknown SpanSenderType: ${value}
• Invalid namespace : <namespace>
• Unknown HbaseClientVersion:<version>
• maxBuckets should be in 1..256 range
• maxBuckets should be in 1..256 range

AI-assisted analysis of pinpoint-apm/pinpoint@744c3d3075 (2026-09-07). Data as JSON: /api/errors/60df7d6faf9f2b9a. Report an issue: GitHub.