pinpoint-apm/pinpoint · error · IllegalArgumentException

sqlUid length must be 16: ${sqlUid.length}

Error message

sqlUid length must be 16: ${sqlUid.length}

What it means

SqlUidMetaDataBo requires the sqlUid byte array to be exactly UidMetaDataRowKey.UID_LENGTH (16 bytes), matching the fixed-width key layout used in HBase storage. A null or wrong-length sqlUid is rejected in the constructor with this IllegalArgumentException.

Source

Thrown at commons-server/src/main/java/com/navercorp/pinpoint/common/server/bo/SqlUidMetaDataBo.java:55

    private final byte[] sqlUid;
    @NonNull
    private final String sql;

    // used by web only
    public SqlUidMetaDataBo(ServiceUid serviceUid, String agentId, long startTime, byte[] sqlUid, String sql) {
        this(serviceUid, agentId, startTime, "", sqlUid, sql);
    }

    public SqlUidMetaDataBo(ServiceUid serviceUid, String agentId, long startTime, String applicationName, byte[] sqlUid, String sql) {
        this.serviceUid = Objects.requireNonNull(serviceUid, "serviceUid");
        this.agentId = StringPrecondition.requireHasLength(agentId, "agentId");
        this.startTime = NumberPrecondition.requirePositiveOrZero(startTime, "startTime");
        this.applicationName = Objects.requireNonNull(applicationName, "applicationName");
        this.sqlUid = Objects.requireNonNull(sqlUid, "sqlUid");
        this.sql = Objects.requireNonNull(sql, "sql");

        if (sqlUid.length != UidMetaDataRowKey.UID_LENGTH) {
            throw new IllegalArgumentException("sqlUid length must be 16: " + sqlUid.length);
        }
    }

    @Override
    public ServiceUid getServiceUid() {
        return serviceUid;
    }

    @Override
    public String getAgentId() {
        return agentId;
    }

    @Override
    public long getAgentStartTime() {
        return startTime;
    }

View on GitHub (pinned to 744c3d3075)

Solutions

1. Ensure the sqlUid is the full 16-byte uid (e.g. a 128-bit hash) before constructing the BO
2. Decode hex/encoded keys back to raw bytes and verify length == 16 prior to construction
3. Regenerate or re-derive the uid from the SQL if the stored key was truncated

Example fix

// before
byte[] uid = sqlUidHex.getBytes(); // wrong: text length, not 16 bytes
new SqlUidMetaDataBo(serviceUid, agentId, startTime, appName, uid, sql);
// after
byte[] uid = DatatypeConverter.parseHexBinary(sqlUidHex);
if (uid.length != UidMetaDataRowKey.UID_LENGTH) {
    throw new IllegalStateException("bad uid length " + uid.length);
}
new SqlUidMetaDataBo(serviceUid, agentId, startTime, appName, uid, sql);

if (sqlUid == null || sqlUid.length != UidMetaDataRowKey.UID_LENGTH) {
    throw new IllegalArgumentException("sqlUid must be exactly " + UidMetaDataRowKey.UID_LENGTH + " bytes");
}
new SqlUidMetaDataBo(serviceUid, agentId, startTime, applicationName, sqlUid, sql);

boolean isValidSqlUid(byte[] uid) {
    return uid != null && uid.length == UidMetaDataRowKey.UID_LENGTH;
}

try {
    return new SqlUidMetaDataBo(serviceUid, agentId, startTime, appName, sqlUid, sql);
} catch (IllegalArgumentException e) {
    logger.warn("Rejecting metadata with bad sqlUid length", e);
    return null;
}

When it happens

Trigger: Constructing SqlUidMetaDataBo with a sqlUid array shorter or longer than 16 bytes, e.g. from parsing a malformed row key, a truncated hash, or passing a hex string's bytes without decoding to the full 16-byte digest.

Common situations: Using a 64-char hex SHA string's first/last bytes instead of the full 16-byte uid; row keys corrupted or re-encoded (e.g. Base64 vs raw) before BO construction; schema changes between Pinpoint versions altering key length.

Understand the failure class

Background: "invalid id" errors: invalid identifier format — why libraries reject IDs before lookup, and how to fix them — this error's family across 37 libraries.

Related errors

• annotationKey name must not be empty
• matcher type must not be empty
• Unknown matcher type :
• value
• negative cache size:${size}

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