{"record":{"id":"60df7d6faf9f2b9a","repo":"pinpoint-apm/pinpoint","slug":"hbase-version-compatibility-violation-hbaseclient","errorCode":null,"errorMessage":"HBase version compatibility violation HBaseClient:%s, HBaseServer:%s","messagePattern":"HBase version compatibility violation HBaseClient:(.+?), HBaseServer:(.+?)","errorType":"exception","errorClass":"HBaseAccessException","httpStatus":null,"severity":"critical","filePath":"commons-hbase/src/main/java/com/navercorp/pinpoint/common/hbase/HbaseVersionCheckBean.java","lineNumber":58,"sourceCode":"        this.hbaseVersionCompatibility = hbaseVersionCompatibility;\n    }\n\n    @Override\n    public void afterPropertiesSet() throws Exception {\n        ClusterMetrics clusterMetrics = template.execute(Admin::getClusterMetrics);\n        logger.info(\"HBase ClusterMetrics:{}\", clusterMetrics);\n\n        String hBaseServerVersion = clusterMetrics.getHBaseVersion();\n        logger.info(\"HBaseServerVersion:{}\", hBaseServerVersion);\n        if (!hbaseVersionCompatibility) {\n            return;\n        }\n\n        HBaseClientVersion hbaseClientVersion = getHbaseClientVersion();\n        if (!hbaseClientVersion.acceptVersion(hBaseServerVersion)) {\n            String error = String.format(\"HBase version compatibility violation HBaseClient:%s, HBaseServer:%s\", hbaseClientVersion, hBaseServerVersion);\n            logger.error(error);\n            throw new HBaseAccessException(error);\n        }\n\n    }\n\n    private HBaseClientVersion getHbaseClientVersion() {\n        final String version = VersionInfo.getVersion();\n        logger.info(\"HBaseClientVersion:{}\", version);\n\n        HBaseClientVersion hBaseClientVersion = HBaseClientVersion.getHBaseVersion(version);\n        if (hBaseClientVersion == null) {\n            throw new HBaseAccessException(\"Unknown HbaseClientVersion:\" + version);\n        }\n        return hBaseClientVersion;\n    }\n}\n","sourceCodeStart":40,"sourceCodeEnd":74,"githubUrl":"https://github.com/pinpoint-apm/pinpoint/blob/744c3d3075e595656abb1ae331ad2c0e4c9eb996/commons-hbase/src/main/java/com/navercorp/pinpoint/common/hbase/HbaseVersionCheckBean.java#L40-L74","documentation":"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.","triggerScenarios":"Spring context initialization of HbaseVersionCheckBean when HBaseClientVersion.acceptVersion(hBaseServerVersion) returns false for the resolved client version (VersionInfo.getVersion()) versus the configured hBaseServerVersion.","commonSituations":"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.","solutions":["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)","Update the hbase.client.version / hbase.server.version configuration properties to versions on the compatibility matrix for your pinpoint version","Upgrade pinpoint commons-hbase/web/collector to a release that supports your HBase server version","If intentionally bypassing, check whether the bean exposes a version-check disable flag in your pinpoint version before disabling it"],"exampleFix":"// before\nhbase.clientVersion=2.4\nhbase.serverVersion=1.2\n// after\nhbase.clientVersion=2.4\nhbase.serverVersion=2.4","handlingStrategy":"validation","validationCode":"String clientV = VersionInfo.getVersion();\nHBaseClientVersion cv = HBaseClientVersion.getHBaseVersion(clientV);\nif (cv == null || !cv.acceptVersion(hBaseServerVersion)) {\n    throw new IllegalStateException(\"Unsupported HBase client/server combination: \" + clientV + \" vs \" + hBaseServerVersion);\n}","typeGuard":null,"tryCatchPattern":"try {\n    applicationContext.refresh(); // or bean init\n} catch (HBaseAccessException e) {\n    logger.fatal(\"HBase version mismatch: {}\", e.getMessage());\n    System.exit(1); // fail fast; do not run with incompatible HBase\n}","preventionTips":["Check the pinpoint/HBase compatibility matrix before upgrading either side","Pin hbase-client dependency versions explicitly in your build","Log client and server versions at startup and alert on drift","Test context startup against the target HBase cluster in CI"],"tags":["hbase","startup","version-compatibility","configuration"],"backgroundTag":"invalid-config-value","analyzedSha":"744c3d3075e595656abb1ae331ad2c0e4c9eb996","analyzedAt":"2026-09-07T18:48:45.289Z","contentChangedAt":"2026-09-07T18:48:45.289Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}