pinpoint-apm/pinpoint · error

INTERNAL_SERVER_ERROR

INTERNAL_SERVER_ERROR

Error message

Failed to handle. agentInfo={}

What it means

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.

Source

Thrown at collector/src/main/java/com/navercorp/pinpoint/collector/handler/grpc/GrpcAgentInfoHandler.java:101

        try {
            final ServiceUid serviceUid;
            try {
                serviceUid = header.getServiceUid().get();
            } catch (UidNotFoundException e) {
                uidLogger.warn("Service not found. serviceName={}, applicationName={}, agentId={}",
                        header.getServiceName(), header.getApplicationName(), header.getAgentId());
                return PResults.serviceNotFound(header.getServiceName());
            }

            // agent info
            final AgentInfoBo agentInfoBo = this.agentInfoBoMapper.map(agentInfo, header);
            this.agentInfoService.insert(agentInfoBo);
            this.applicationIndexV2Service.insert(serviceUid, header.getServiceType(), agentInfoBo);
            this.agentInfoStatisticsService.insert(serviceUid, header.getApplicationName(), agentInfoBo);
            return PResults.SUCCESS;
        } catch (Exception e) {
            logger.warn("Failed to handle. agentInfo={}", MessageFormatUtils.debugLog(agentInfo), e);
            // Avoid detailed error messages.
            return PResults.INTERNAL_SERVER_ERROR;
        }
    }
}

View on GitHub (pinned to 744c3d3075)

Solutions

1. Inspect the collector log at WARN for the full stack trace following 'Failed to handle. agentInfo=' — the suppressed detail is there.
2. Verify HBase health (HBase shell status, region servers up, target tables enabled) and connectivity from the collector.
3. 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.
4. Check the incoming agent payload: applicationName, agentId, serviceType must be non-null and valid.
5. After fixing storage, have the agent reconnect/re-send agent info (restarting the agent triggers re-registration).

Example fix

// before (collector side, opaque failure)
return PResults.INTERNAL_SERVER_ERROR;

// after (operational check before upgrade: apply schema, then verify)
// hbase shell: status; exists 'AgentInfo'; exists 'ApplicationIndex'
// and keep stack trace in logs instead of only message
catch (Exception e) {
    logger.warn("Failed to handle. agentInfo={}", MessageFormatUtils.debugLog(agentInfo), e); // keep e for root cause
    return PResults.INTERNAL_SERVER_ERROR;
}

// client-side (agent/embedding code) pre-checks before sending agent info
if (agentInfo == null) throw new IllegalArgumentException("agentInfo is required");
if (agentInfo.getApplicationName() == null || agentInfo.getApplicationName().isEmpty())
    throw new IllegalArgumentException("applicationName must not be empty");
if (agentInfo.getAgentId() == null || agentInfo.getAgentId().isEmpty())
    throw new IllegalArgumentException("agentId must not be empty");
// and verify storage reachability before starting the collector
// hbase shell: status; exists 'AgentInfo'

// Java: guard required header fields before invoking the handler
private static boolean isValidAgentRequest(PS_AgentInfo agentInfo, AgentInfoHeader header) {
    return agentInfo != null && header != null
        && header.getApplicationName() != null && !header.getApplicationName().isEmpty()
        && header.getAgentId() != null;
}

try {
    PResult result = grpcAgentInfoHandler.handleAgentInfo(agentInfo, header);
    if (!PResults.isSuccess(result)) {
        // schedule retry with backoff; agent info is re-sent on reconnect anyway
        retryScheduler.schedule(() -> resendAgentInfo(), backoff);
    }
} catch (StatusRuntimeException e) {
    logger.warn("agentInfo RPC failed: {}", e.getStatus(), e);
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• INTERNAL_SERVER_ERROR
• INTERNAL_SERVER_ERROR
• INTERNAL_SERVER_ERROR
• INTERNAL_SERVER_ERROR
• Failed to send agentInfo={}. request unsuccessful, response=

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