pinpoint-apm/pinpoint · info · ResponseStatusException

agent status not found

Error message

agent status not found

What it means

HTTP 404 guard in AgentInfoController.getAgentStatus: when agentInfoService cannot find a status record for the given agentId at the requested timestamp, the controller translates the null result into a ResponseStatusException with NOT_FOUND. It fires for unknown agent ids, agents outside the data retention window, or timestamps with no status snapshot. The input at fault is the agentId/timestamp query pair; callers should verify the agent existed and was active at that time.

Source

Thrown at web/src/main/java/com/navercorp/pinpoint/web/authorization/controller/AgentInfoController.java:106

    public DetailedAgentAndStatus getDetailedAgentInfo(
            @ServiceParam ServiceName serviceName,
            @RequestParam("agentId") @NotBlank String agentId,
            @RequestParam("timestamp") Timestamp timestamp) {
        DetailedAgentAndStatus result = this.agentInfoService.findDetailedAgentInfoAndStatus(agentId, timestamp.getEpochMillis());
        if (result == null) {
            throw new ResponseStatusException(HttpStatus.NOT_FOUND, "detailed agent info not found");
        }
        return result;
    }

    @GetMapping(value = "/getAgentStatus")
    public AgentStatus getAgentStatus(
            @ServiceParam ServiceName serviceName,
            @RequestParam("agentId") @NotBlank String agentId,
            @RequestParam("timestamp") Timestamp timestamp) {
        AgentStatus result = this.agentInfoService.findAgentStatus(agentId, timestamp.getEpochMillis());
        if (result == null) {
            throw new ResponseStatusException(HttpStatus.NOT_FOUND, "agent status not found");
        }
        return result;
    }

    @GetMapping(value = "/getAgentEvent")
    public AgentEvent getAgentEvent(
            @ServiceParam ServiceName serviceName,
            @RequestParam("agentId") @NotBlank String agentId,
            @RequestParam("eventTimestamp") Timestamp eventTimestamp,
            @RequestParam("eventTypeCode") int eventTypeCode
    ) {
        final AgentEventType eventType = AgentEventType.getTypeByCode(eventTypeCode);
        if (eventType == null) {
            throw new IllegalArgumentException("invalid eventTypeCode [" + eventTypeCode + "]");
        }

        AgentEvent result = this.agentEventService.getAgentEvent(agentId, eventTimestamp.getEpochMillis(), eventType);
        if (result == null) {

View on GitHub (pinned to 744c3d3075)

Solutions

  1. Query a timestamp during the agent's known active window
  2. Verify the agentId
  3. If agent info exists but status never does, check agent lifecycle event data in HBase
Defensive patterns

Strategy: fallback

Validate before calling

if (timestamp == null || timestamp.getEpochMillis() <= 0) throw new IllegalArgumentException("valid timestamp required");

Try / catch

try { return api.getAgentStatus(id, ts); } catch (ResponseStatusException e) { if (e.getStatus() == HttpStatus.NOT_FOUND) return AgentStatus.UNKNOWN; throw e; }

Prevention

When it happens

Trigger: GET /getAgentStatus?agentId=X&timestamp=Y where no lifecycle/status record exists for that agent at that epoch millis.

Common situations: Timestamp before the agent registered or after its data was purged; agentId misspelled; status data missing despite agentInfo existing (incomplete lifecycle records).

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

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