What causes "Failed to insert agentInfoBo" in pinpoint-apm/pinpoint?

Check the throttled stack trace to see whether AgentInfo or ApplicationIndexV2 write failed.

Failed to insert agentInfoBo

Error message

Failed to insert agentInfoBo

What it means

OtlpTraceExportService.export writes each AgentInfoBo via agentInfoService.insert and applicationIndexV2Service.insert, then caches the agentId; any exception in these HBase writes increments agentInfoErrorCount, bumps agentInfoInsertErrorCounter, and logs this throttled warning. Note the agentId is only cached after success, so failed agents are retried on next export.

Source

Thrown at otlptrace/otlptrace-collector/src/main/java/com/navercorp/pinpoint/otlp/trace/collector/service/OtlpTraceExportService.java:177

                } catch (Exception e) {
                    insertErrorCount++;
                    spanChunkInsertErrorCounter.increment();
                    throttledLogger.warn("Failed to insert spanChunkBo", e);
                }
            }
        }

        int agentInfoErrorCount = 0;
        for (AgentInfoBo agentInfoBo : otlpTraceMapperData.getAgentInfoBoList()) {
            if (agentIdCache.getIfPresent(agentInfoBo.getAgentId()) == null) {
                try {
                    agentInfoService.insert(agentInfoBo);
                    applicationIndexV2Service.insert(DEFAULT_SERVICE_UID, agentInfoBo);
                    agentIdCache.put(agentInfoBo.getAgentId(), Boolean.TRUE);
                } catch (Exception e) {
                    agentInfoErrorCount++;
                    agentInfoInsertErrorCounter.increment();
                    throttledLogger.warn("Failed to insert agentInfoBo", e);
                }
            }
        }

        if (exceptionMetaDataService != null) {
            for (ExceptionMetaDataBo exceptionMetaDataBo : otlpTraceMapperData.getExceptionMetaDataBoList()) {
                try {
                    exceptionMetaDataService.save(exceptionMetaDataBo);
                } catch (Exception e) {
                    exceptionInsertErrorCounter.increment();
                    throttledLogger.warn("Failed to insert exceptionMetaData", e);
                }
            }
        }

        // Optional statistics side channel: a uriStat failure must not fail the trace export, so it
        // is not counted toward serverErrorCount (spans are already stored at this point).
        if (uriStatService != null) {

View on GitHub (pinned to 744c3d3075)

Solutions

Check the throttled stack trace to see whether AgentInfo or ApplicationIndexV2 write failed.
Verify both HBase table families exist with correct schema (run pinpoint HBase scripts).
Confirm DEFAULT_SERVICE_UID configuration matches the v2 index expectations.
Retry/resend agent info — the agentId cache skips only successfully inserted agents.

Defensive patterns

Strategy: retry

Validate before calling

if (agentInfoBo == null || agentInfoBo.getAgentId() == null || agentInfoBo.getApplicationName() == null) {
    logger.warn("Skipping invalid AgentInfoBo: missing agentId/applicationName");
    return;
}

Try / catch

try {
    agentInfoService.insert(agentInfoBo);
    applicationIndexV2Service.insert(DEFAULT_SERVICE_UID, agentInfoBo);
    agentIdCache.put(agentInfoBo.getAgentId(), Boolean.TRUE);
} catch (Exception e) {
    // do NOT put agentId into cache; next export retries naturally
    agentInfoInsertErrorCounter.increment();
    logger.warn("Failed to insert agentInfoBo for {}", agentInfoBo.getAgentId(), e);
}

Prevention

Run the pinpoint HBase table creation scripts so AgentInfo and v2 application index tables exist.
Rely on the agentIdCache-on-success pattern so failed inserts are retried on the next export.
Watch agent storms after mass agent restarts and stagger collector load.
Verify DEFAULT_SERVICE_UID configuration matches the v2 index requirements.

When it happens

Trigger: agentInfoService.insert(agentInfoBo) or applicationIndexV2Service.insert(DEFAULT_SERVICE_UID, agentInfoBo) throws synchronously during the agentInfo loop of export().

Common situations: AgentInfo or application-index HBase tables misconfigured/unavailable; HBase overload from agent storm after mass agent restart; service UID v2 tables not created after upgrade.

Related errors

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