pinpoint-apm/pinpoint · error · ResponseStatusException

agentId already exists

Error message

agentId already exists

What it means

After passing length and pattern checks, isAvailableAgentId checks agentInfoService.findAgentInfo(agentId, now); if the id already exists it throws HTTP 500 'agentId already exists' (note: 500 despite being a client-side conflict).

Solutions

1. Choose a different, unique agentId
2. Remove/purge the old agent's data or wait for it to be deactivated before reuse
3. Treat the 500 as 'id taken' and pick another candidate

Example fix

// before
if (available(id)) register(id);
// after
if (http.get("/isAvailableAgentId?agentId=" + id).status == 200) register(id);
else id = id + "-" + uniqueSuffix;

boolean taken = api.getAgentInfo(agentId, System.currentTimeMillis()) != null; if (taken) throw new IllegalStateException("agentId already exists: " + agentId);

try { return api.isAvailableAgentId(id); } catch (ResponseStatusException e) { if (e.getStatus() == HttpStatus.INTERNAL_SERVER_ERROR && "agentId already exists".equals(e.getReason())) return pickAlternativeId(id); throw e; }

When it happens

Trigger: GET /isAvailableAgentId for an id that an agent has already registered with data present at System.currentTimeMillis().

Common situations: Reinstalling/reusing an old agentId without cleanup; two agents configured with the same id; testing id availability for an id that's actively running.

Understand the failure class

Background: "already exists" / EEXIST / FileAlreadyExistsException: what the 'file already exists' error means and how to fix it — this error's family across 37 libraries.

Related errors

• agent event not found
• agent info not found
• agent status not found
• application serviceType not found. code
• application serviceType not found. code

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

Appendix: source

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

        final Range range = Range.between(from, to);
        rangeValidator.validate(range);
        return agentInfoService.getAgentStatusTimeline(serviceName.getName(), applicationName, agentId, range, excludeEventTypeCodes);
    }

    @RequestMapping(value = "/isAvailableAgentId")
    public CodeResult<String> isAvailableAgentId(@ServiceParam ServiceName serviceName, @RequestParam("agentId") @NotBlank String agentId) {
        final IdValidateUtils.CheckResult result = IdValidateUtils.checkId(agentId, PinpointConstants.AGENT_ID_MAX_LEN);
        if (result == IdValidateUtils.CheckResult.FAIL_LENGTH) {
            throw new ResponseStatusException(HttpStatus.BAD_REQUEST, "length range is 1 ~ 24");
        }
        if (result == IdValidateUtils.CheckResult.FAIL_PATTERN) {
            throw new ResponseStatusException(
                    HttpStatus.BAD_REQUEST,
                    "invalid pattern(" + IdValidateUtils.ID_PATTERN_VALUE + ")"
            );
        }
        if (agentInfoService.findAgentInfo(agentId, System.currentTimeMillis()) != null) {
            throw new ResponseStatusException(HttpStatus.INTERNAL_SERVER_ERROR, "agentId already exists");
        }
        return CodeResult.ok("OK");
    }

}

View on GitHub (pinned to 744c3d3075)