What causes "Failed to handle exceptionMetaData={}" in pinpoint-apm/pinpoint?

Check the collector WARN log 'Failed to handle exceptionMetaData=' for the full stack trace (the actual cause).

INTERNAL_SERVER_ERROR

INTERNAL_SERVER_ERROR

Error message

Failed to handle exceptionMetaData={}

What it means

Catch-all failure path of GrpcExceptionMetaDataHandler.handleExceptionMetaData. Any exception thrown while mapping the PS_ExceptionMetaData into an ExceptionMetaDataBo (mapExceptionMetaDataBo) or saving it via exceptionMetaDataService.save is caught, logged at WARN with a debug rendering of the metadata and the full stack trace, and turned into PResults.INTERNAL_SERVER_ERROR returned to the agent. The gRPC response intentionally omits the root cause.

Source

Thrown at collector/src/main/java/com/navercorp/pinpoint/collector/handler/grpc/GrpcExceptionMetaDataHandler.java:87

    private PResult handleExceptionMetaData(final ServerHeader header, final PExceptionMetaData exceptionMetaData) {
        if (isDebug) {
            logger.debug("Handle PExceptionMetaData={}", MessageFormatUtils.debugLog(exceptionMetaData));
        }

        try {
            ExceptionMetaDataBo exceptionMetaDataBo = mapExceptionMetaDataBo(header, exceptionMetaData);

            List<ExceptionWrapperBo> exceptionWrapperBos = mapExceptionWrapperBo(
                    exceptionMetaData.getExceptionsList(), header
            );
            exceptionMetaDataBo.setExceptionWrapperBos(exceptionWrapperBos);


            exceptionMetaDataService.save(exceptionMetaDataBo);

            return PResults.SUCCESS;
        } catch (Exception e) {
            logger.warn("Failed to handle exceptionMetaData={}", MessageFormatUtils.debugLog(exceptionMetaData), e);
            // Avoid detailed error messages.
            return PResults.INTERNAL_SERVER_ERROR;
        }
    }

    private ExceptionMetaDataBo mapExceptionMetaDataBo(
            ServerHeader agentInfo, PExceptionMetaData exceptionMetaData
    ) {
        final String agentId = agentInfo.getAgentId();
        final ServerTraceId transactionId = newTransactionId(exceptionMetaData.getTransactionId(), agentId);

        return new ExceptionMetaDataBo(
                transactionId, exceptionMetaData.getSpanId(),
                (short) agentInfo.getServiceType(),
                agentInfo.getServiceName(),
                agentInfo.getApplicationName(),
                agentInfo.getAgentId(),
                StringUtils.defaultIfEmpty(exceptionMetaData.getUriTemplate(), EMPTY)

View on GitHub (pinned to 744c3d3075)

Solutions

Check the collector WARN log 'Failed to handle exceptionMetaData=' for the full stack trace (the actual cause).
Ensure the ExceptionMetaData HBase table exists and matches the deployed Pinpoint version's schema (apply the feature's hbase scripts).
Confirm HBase connectivity/health from the collector (zookeeper quorum, region servers).
Inspect the logged exceptionMetaData payload for invalid/null fields; disable exception metadata on agents or upgrade collector/agents to matching versions if skew is the cause.
Retry after storage recovery — agents resend exception metadata on subsequent occurrences.

Example fix

// before
exceptionMetaDataService.save(exceptionMetaDataBo);
return PResults.SUCCESS;
// ... catch -> return PResults.INTERNAL_SERVER_ERROR;

// after: verify table presence for the feature before deployment
// hbase shell: exists 'ExceptionMetaData' || apply pinpoint hbase schema scripts
exceptionMetaDataService.save(exceptionMetaDataBo); // failures logged with full stack trace

Defensive patterns

Strategy: try-catch

Validate before calling

// pre-check exception metadata payload before sending
if (exceptionMetaData == null || exceptionMetaData.getApplicationName() == null)
    throw new IllegalArgumentException("exceptionMetaData requires applicationName");
// ensure the feature's table exists: hbase shell: exists 'ExceptionMetaData'

Type guard

// Java: narrow valid requests before invoking the handler
private static boolean isUsableExceptionMetaData(PS_ExceptionMetaData m) {
    return m != null && m.getClassName() != null && !m.getClassName().isEmpty();
}

Try / catch

try {
    PResult result = handler.handleExceptionMetaData(exceptionMetaData);
    if (!PResults.isSuccess(result)) {
        // non-fatal: exception metadata will recur; just rate-limit logging
        logger.debug("exception metadata write rejected; will retry on next occurrence");
    }
} catch (StatusRuntimeException e) {
    logger.warn("exceptionMetaData RPC failed: {}", e.getStatus(), e);
}

Prevention

Only enable exception tracking when the collector and its HBase tables support it (match agent/collector versions).
Run the exception-metadata hbase scripts when enabling the feature.
Watch HBase health; the failure is almost always storage-side since the handler suppresses cause details.
Inspect the debugLog rendering in WARN logs to spot payload-driven failures.

When it happens

Trigger: Any exception in handleExceptionMetaData: invalid exception metadata fields in the request (null className/message/uri, bad transaction/exception ids), a mapping exception, or a storage failure from exceptionMetaDataService.save.

Common situations: HBase outage or ExceptionMetaData table not created for the deployed Pinpoint version (exception-tracking is a newer feature; older tables lack it); version skew where a newer agent sends exception metadata to an older collector/table setup; oversized exception messages/stack frames; collector misconfiguration of the exception metadata table.

Related errors

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