{"record":{"id":"2396cebc85845cfc","repo":"pinpoint-apm/pinpoint","slug":"internal-server-error-2396ce","errorCode":"INTERNAL_SERVER_ERROR","errorMessage":"Failed to handle apiMetaData={}","messagePattern":"Failed to handle apiMetaData=(.+?)","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"error","filePath":"collector/src/main/java/com/navercorp/pinpoint/collector/handler/grpc/GrpcApiMetaDataHandler.java","lineNumber":86,"sourceCode":"                logger.warn(\"Service not found. serviceName={}, serviceUid={}, applicationName={}, agentId={}\",\n                        header.getServiceName(), serviceUid, header.getApplicationName(), header.getAgentId());\n                return PResults.serviceNotFound(header.getServiceName());\n            }\n\n            final String agentId = header.getAgentId();\n            final long agentStartTime = header.getAgentStartTime();\n            final int line = LineNumber.defaultLineNumber(apiMetaData.getLine());\n\n            final MethodTypeEnum type = MethodTypeEnum.defaultValueOf(apiMetaData.getType());\n\n            final ApiMetaDataBo apiMetaDataBo = new ApiMetaDataBo.Builder(serviceUid, agentId, agentStartTime, apiMetaData.getApiId(), line, type, apiMetaData.getApiInfo())\n                    .setLocation(apiMetaData.getLocation())\n                    .build();\n\n            this.apiMetaDataService.insert(apiMetaDataBo);\n            return PResults.SUCCESS;\n        } catch (Exception e) {\n            logger.warn(\"Failed to handle apiMetaData={}\", MessageFormatUtils.debugLog(apiMetaData), e);\n            // Avoid detailed error messages.\n            return PResults.INTERNAL_SERVER_ERROR;\n        }\n    }\n}","sourceCodeStart":68,"sourceCodeEnd":91,"githubUrl":"https://github.com/pinpoint-apm/pinpoint/blob/744c3d3075e595656abb1ae331ad2c0e4c9eb996/collector/src/main/java/com/navercorp/pinpoint/collector/handler/grpc/GrpcApiMetaDataHandler.java#L68-L91","documentation":"Catch-all failure path of GrpcApiMetaDataHandler.handleApiMetaData. Any exception while building the ApiMetaDataBo or inserting it via apiMetaDataService.insert (an HBase-backed write of the method-to-apiId mapping) is logged at WARN with a debug-rendered apiMetaData and stack trace, then converted into PResults.INTERNAL_SERVER_ERROR returned to the agent. The real cause is hidden from the gRPC response on purpose.","triggerScenarios":"Any exception in handleApiMetaData: malformed PS_ApiMetaData request fields, exception while composing ApiMetaDataBo, or a storage exception from apiMetaDataService.insert.","commonSituations":"HBase unavailable or ApiMetaData table missing/mis-scoped (wrong table name in collector config); schema drift after Pinpoint upgrade (e.g. apiUid columns added without table migration); duplicate/racing inserts from many agents hammering the same method signature; corrupt or oversized method descriptors (very long line numbers/locations) from instrumented agents.","solutions":["Read the WARN log 'Failed to handle apiMetaData=' in the collector for the underlying stack trace.","Check HBase availability and that the ApiMetaData table exists with the schema matching your Pinpoint version (run hbase schema scripts).","Verify collector HBase client configuration (zookeeper quorum, table namespace).","Inspect the payload in the log (debugLog renders the apiMetaData) for null/absurd fields; update or fix the offending agent if its bytecode instrumentation produces bad descriptors.","Restart affected agents so they re-send api metadata once storage is healthy."],"exampleFix":"// before\nreturn PResults.INTERNAL_SERVER_ERROR;\n\n// after: keep the exception in the log (it already is) and ensure the table exists\n// hbase shell: create 'ApiMetaData', ...\nthis.apiMetaDataService.insert(apiMetaDataBo); // throws -> logged with full stack trace\nreturn PResults.INTERNAL_SERVER_ERROR;","handlingStrategy":"retry","validationCode":"// pre-check before registering api metadata\nif (apiMetaData == null || apiMetaData.getAgentId() == null || apiMetaData.getApplicationName() == null)\n    throw new IllegalArgumentException(\"apiMetaData requires agentId and applicationName\");\n// verify table exists: hbase shell: exists 'ApiMetaData'","typeGuard":"// Java: validate the gRPC payload shape before the call\nprivate static boolean isWellFormedApiMetaData(PS_ApiMetaData m) {\n    return m != null && !m.getApiDescriptor().isEmpty() && m.getApplicationName() != null;\n}","tryCatchPattern":"try {\n    PResult result = handler.handleApiMetaData(apiMetaData);\n    if (!PResults.isSuccess(result)) {\n        backoffRetry(() -> handler.handleApiMetaData(apiMetaData));\n    }\n} catch (StatusRuntimeException e) {\n    logger.warn(\"apiMetaData RPC failed: {}\", e.getStatus(), e);\n}","preventionTips":["Apply schema scripts for ApiMetaData whenever upgrading Pinpoint collector.","Alert on HBase Put/Write failures and region server availability.","Grep collector WARN logs for 'Failed to handle apiMetaData' as part of deployment smoke tests.","Keep api descriptor payloads bounded; fix plugins producing degenerate descriptors."],"tags":["grpc","hbase","metadata","collector","api-metadata"],"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"}