{"record":{"id":"1c3a54c0db5b2ebc","repo":"pinpoint-apm/pinpoint","slug":"internal-server-error-1c3a54","errorCode":"INTERNAL_SERVER_ERROR","errorMessage":"Failed to handle exceptionMetaData={}","messagePattern":"Failed to handle exceptionMetaData=(.+?)","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"error","filePath":"collector/src/main/java/com/navercorp/pinpoint/collector/handler/grpc/GrpcExceptionMetaDataHandler.java","lineNumber":87,"sourceCode":"    private PResult handleExceptionMetaData(final ServerHeader header, final PExceptionMetaData exceptionMetaData) {\n        if (isDebug) {\n            logger.debug(\"Handle PExceptionMetaData={}\", MessageFormatUtils.debugLog(exceptionMetaData));\n        }\n\n        try {\n            ExceptionMetaDataBo exceptionMetaDataBo = mapExceptionMetaDataBo(header, exceptionMetaData);\n\n            List<ExceptionWrapperBo> exceptionWrapperBos = mapExceptionWrapperBo(\n                    exceptionMetaData.getExceptionsList(), header\n            );\n            exceptionMetaDataBo.setExceptionWrapperBos(exceptionWrapperBos);\n\n\n            exceptionMetaDataService.save(exceptionMetaDataBo);\n\n            return PResults.SUCCESS;\n        } catch (Exception e) {\n            logger.warn(\"Failed to handle exceptionMetaData={}\", MessageFormatUtils.debugLog(exceptionMetaData), e);\n            // Avoid detailed error messages.\n            return PResults.INTERNAL_SERVER_ERROR;\n        }\n    }\n\n    private ExceptionMetaDataBo mapExceptionMetaDataBo(\n            ServerHeader agentInfo, PExceptionMetaData exceptionMetaData\n    ) {\n        final String agentId = agentInfo.getAgentId();\n        final ServerTraceId transactionId = newTransactionId(exceptionMetaData.getTransactionId(), agentId);\n\n        return new ExceptionMetaDataBo(\n                transactionId, exceptionMetaData.getSpanId(),\n                (short) agentInfo.getServiceType(),\n                agentInfo.getServiceName(),\n                agentInfo.getApplicationName(),\n                agentInfo.getAgentId(),\n                StringUtils.defaultIfEmpty(exceptionMetaData.getUriTemplate(), EMPTY)","sourceCodeStart":69,"sourceCodeEnd":105,"githubUrl":"https://github.com/pinpoint-apm/pinpoint/blob/744c3d3075e595656abb1ae331ad2c0e4c9eb996/collector/src/main/java/com/navercorp/pinpoint/collector/handler/grpc/GrpcExceptionMetaDataHandler.java#L69-L105","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"// before\nexceptionMetaDataService.save(exceptionMetaDataBo);\nreturn PResults.SUCCESS;\n// ... catch -> return PResults.INTERNAL_SERVER_ERROR;\n\n// after: verify table presence for the feature before deployment\n// hbase shell: exists 'ExceptionMetaData' || apply pinpoint hbase schema scripts\nexceptionMetaDataService.save(exceptionMetaDataBo); // failures logged with full stack trace","handlingStrategy":"try-catch","validationCode":"// pre-check exception metadata payload before sending\nif (exceptionMetaData == null || exceptionMetaData.getApplicationName() == null)\n    throw new IllegalArgumentException(\"exceptionMetaData requires applicationName\");\n// ensure the feature's table exists: hbase shell: exists 'ExceptionMetaData'","typeGuard":"// Java: narrow valid requests before invoking the handler\nprivate static boolean isUsableExceptionMetaData(PS_ExceptionMetaData m) {\n    return m != null && m.getClassName() != null && !m.getClassName().isEmpty();\n}","tryCatchPattern":"try {\n    PResult result = handler.handleExceptionMetaData(exceptionMetaData);\n    if (!PResults.isSuccess(result)) {\n        // non-fatal: exception metadata will recur; just rate-limit logging\n        logger.debug(\"exception metadata write rejected; will retry on next occurrence\");\n    }\n} catch (StatusRuntimeException e) {\n    logger.warn(\"exceptionMetaData RPC failed: {}\", e.getStatus(), e);\n}","preventionTips":["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."],"tags":["grpc","hbase","exception-metadata","collector","storage-write"],"backgroundTag":"database-write-failed","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"}