{"record":{"id":"f391d93930fed1c3","repo":"pinpoint-apm/pinpoint","slug":"internal-server-error","errorCode":"INTERNAL_SERVER_ERROR","errorMessage":"Failed to handle. agentInfo={}","messagePattern":"Failed to handle\\. agentInfo=(.+?)","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"error","filePath":"collector/src/main/java/com/navercorp/pinpoint/collector/handler/grpc/GrpcAgentInfoHandler.java","lineNumber":101,"sourceCode":"\n        try {\n            final ServiceUid serviceUid;\n            try {\n                serviceUid = header.getServiceUid().get();\n            } catch (UidNotFoundException e) {\n                uidLogger.warn(\"Service not found. serviceName={}, applicationName={}, agentId={}\",\n                        header.getServiceName(), header.getApplicationName(), header.getAgentId());\n                return PResults.serviceNotFound(header.getServiceName());\n            }\n\n            // agent info\n            final AgentInfoBo agentInfoBo = this.agentInfoBoMapper.map(agentInfo, header);\n            this.agentInfoService.insert(agentInfoBo);\n            this.applicationIndexV2Service.insert(serviceUid, header.getServiceType(), agentInfoBo);\n            this.agentInfoStatisticsService.insert(serviceUid, header.getApplicationName(), agentInfoBo);\n            return PResults.SUCCESS;\n        } catch (Exception e) {\n            logger.warn(\"Failed to handle. agentInfo={}\", MessageFormatUtils.debugLog(agentInfo), e);\n            // Avoid detailed error messages.\n            return PResults.INTERNAL_SERVER_ERROR;\n        }\n    }\n}","sourceCodeStart":83,"sourceCodeEnd":106,"githubUrl":"https://github.com/pinpoint-apm/pinpoint/blob/744c3d3075e595656abb1ae331ad2c0e4c9eb996/collector/src/main/java/com/navercorp/pinpoint/collector/handler/grpc/GrpcAgentInfoHandler.java#L83-L106","documentation":"This is the catch-all failure path of Pinpoint collector's GrpcAgentInfoHandler.handleAgentInfo. Any exception thrown while mapping the incoming PS_AgentInfo protobuf to an AgentInfoBo or while writing it (agentInfoService.insert, applicationIndexV2Service.insert, agentInfoStatisticsService.insert) is swallowed, logged at WARN, and converted into an INTERNAL_SERVER_ERROR result returned to the gRPC caller. The detailed message is intentionally suppressed ('Avoid detailed error messages'), so the log line only shows a debug-rendered agentInfo plus the stack trace.","triggerScenarios":"Any exception inside handleAgentInfo: null header/applicationName on the request, a mapping exception in agentInfoBoMapper.map, or an HBase/storage failure in agentInfoService.insert, applicationIndexV2Service.insert (serviceUid write), or agentInfoStatisticsService.insert.","commonSituations":"HBase cluster down, unreachable, or in a bad state (region servers overloaded, table disabled); schema/serialization mismatch after a Pinpoint version upgrade (new column added to AgentInfoBo but HBase table not migrated); invalid agent info payload from an old or buggy agent (missing applicationName/serviceType); serviceUid/applicationIndex features enabled without the corresponding tables created.","solutions":["Inspect the collector log at WARN for the full stack trace following 'Failed to handle. agentInfo=' — the suppressed detail is there.","Verify HBase health (HBase shell status, region servers up, target tables enabled) and connectivity from the collector.","Ensure all required HBase tables exist and schemas match the collector version (AgentInfo, ApplicationIndex, statistics tables); run the hbase schema scripts for your Pinpoint version.","Check the incoming agent payload: applicationName, agentId, serviceType must be non-null and valid.","After fixing storage, have the agent reconnect/re-send agent info (restarting the agent triggers re-registration)."],"exampleFix":"// before (collector side, opaque failure)\nreturn PResults.INTERNAL_SERVER_ERROR;\n\n// after (operational check before upgrade: apply schema, then verify)\n// hbase shell: status; exists 'AgentInfo'; exists 'ApplicationIndex'\n// and keep stack trace in logs instead of only message\ncatch (Exception e) {\n    logger.warn(\"Failed to handle. agentInfo={}\", MessageFormatUtils.debugLog(agentInfo), e); // keep e for root cause\n    return PResults.INTERNAL_SERVER_ERROR;\n}","handlingStrategy":"try-catch","validationCode":"// client-side (agent/embedding code) pre-checks before sending agent info\nif (agentInfo == null) throw new IllegalArgumentException(\"agentInfo is required\");\nif (agentInfo.getApplicationName() == null || agentInfo.getApplicationName().isEmpty())\n    throw new IllegalArgumentException(\"applicationName must not be empty\");\nif (agentInfo.getAgentId() == null || agentInfo.getAgentId().isEmpty())\n    throw new IllegalArgumentException(\"agentId must not be empty\");\n// and verify storage reachability before starting the collector\n// hbase shell: status; exists 'AgentInfo'","typeGuard":"// Java: guard required header fields before invoking the handler\nprivate static boolean isValidAgentRequest(PS_AgentInfo agentInfo, AgentInfoHeader header) {\n    return agentInfo != null && header != null\n        && header.getApplicationName() != null && !header.getApplicationName().isEmpty()\n        && header.getAgentId() != null;\n}","tryCatchPattern":"try {\n    PResult result = grpcAgentInfoHandler.handleAgentInfo(agentInfo, header);\n    if (!PResults.isSuccess(result)) {\n        // schedule retry with backoff; agent info is re-sent on reconnect anyway\n        retryScheduler.schedule(() -> resendAgentInfo(), backoff);\n    }\n} catch (StatusRuntimeException e) {\n    logger.warn(\"agentInfo RPC failed: {}\", e.getStatus(), e);\n}","preventionTips":["Keep collector logs at WARN/DEBUG in staging so the suppressed stack traces reveal root causes early.","Run the Pinpoint hbase schema scripts matching your collector version on every upgrade.","Monitor HBase region server health and collector-to-HBase connectivity with alerts.","Pin agent and collector versions to compatible releases; avoid sending new fields to older collectors.","Restart agents after any storage incident so agent info is re-registered."],"tags":["grpc","hbase","agent-registration","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"}