pinpoint-apm/pinpoint · error · HBaseAccessException

Unknown HbaseClientVersion:<version>

Error message

Unknown HbaseClientVersion:<version>

What it means

Thrown by getHbaseClientVersion when VersionInfo.getVersion() returns a string that HBaseClientVersion.getHBaseVersion cannot map to a known HBaseClientVersion enum. The bean refuses to guess compatibility with an unrecognized client runtime version.

Source

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

            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. Check the logged 'HBaseClientVersion:<version>' line and replace the hbase-client dependency with a mainstream version supported by the enum
  2. Align pinpoint's commons-hbase/hbase client dependency to a released, non-fork HBase version matching the server
  3. Upgrade pinpoint so HBaseClientVersion includes your HBase version
  4. Inspect the HBaseClientVersion enum source for the accepted version strings and pick a matching dependency

Example fix

// before (pom)
<artifactId>hbase-client</artifactId><version>2.5.9-hadoop3-custom-fork</version>
// after
<artifactId>hbase-client</artifactId><version>2.4.17</version>
Defensive patterns

Strategy: validation

Validate before calling

String v = VersionInfo.getVersion();
if (HBaseClientVersion.getHBaseVersion(v) == null) {
    throw new IllegalStateException("HBase client version not recognized by pinpoint: " + v);
}

Try / catch

try {
    bean.afterPropertiesSet();
} catch (HBaseAccessException e) {
    logger.error("Unrecognized HBase client version: {}", e.getMessage());
    // replace hbase-client dependency or upgrade pinpoint
}

Prevention

When it happens

Trigger: HbaseVersionCheckBean startup where HBaseClientVersion.getHBaseVersion(version) returns null because the hbase-client jar on the classpath reports a version string outside the known enum set.

Common situations: Mixing HBase client jars of unusual/patch versions (e.g. 2.5.x-SNAPSHOT, vendor forks like CDH/HDP reporting custom versions); shaded or relocated hbase-client artifacts whose VersionInfo reads differently.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

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