{"record":{"id":"6ffa2528de445a70","repo":"pinpoint-apm/pinpoint","slug":"agentid-already-exists","errorCode":null,"errorMessage":"agentId already exists","messagePattern":"agentId already exists","errorType":"http","errorClass":"ResponseStatusException","httpStatus":500,"severity":"error","filePath":"web/src/main/java/com/navercorp/pinpoint/web/authorization/controller/AgentInfoController.java","lineNumber":194,"sourceCode":"        final Range range = Range.between(from, to);\n        rangeValidator.validate(range);\n        return agentInfoService.getAgentStatusTimeline(serviceName.getName(), applicationName, agentId, range, excludeEventTypeCodes);\n    }\n\n    @RequestMapping(value = \"/isAvailableAgentId\")\n    public CodeResult<String> isAvailableAgentId(@ServiceParam ServiceName serviceName, @RequestParam(\"agentId\") @NotBlank String agentId) {\n        final IdValidateUtils.CheckResult result = IdValidateUtils.checkId(agentId, PinpointConstants.AGENT_ID_MAX_LEN);\n        if (result == IdValidateUtils.CheckResult.FAIL_LENGTH) {\n            throw new ResponseStatusException(HttpStatus.BAD_REQUEST, \"length range is 1 ~ 24\");\n        }\n        if (result == IdValidateUtils.CheckResult.FAIL_PATTERN) {\n            throw new ResponseStatusException(\n                    HttpStatus.BAD_REQUEST,\n                    \"invalid pattern(\" + IdValidateUtils.ID_PATTERN_VALUE + \")\"\n            );\n        }\n        if (agentInfoService.findAgentInfo(agentId, System.currentTimeMillis()) != null) {\n            throw new ResponseStatusException(HttpStatus.INTERNAL_SERVER_ERROR, \"agentId already exists\");\n        }\n        return CodeResult.ok(\"OK\");\n    }\n\n}\n","sourceCodeStart":176,"sourceCodeEnd":200,"githubUrl":"https://github.com/pinpoint-apm/pinpoint/blob/744c3d3075e595656abb1ae331ad2c0e4c9eb996/web/src/main/java/com/navercorp/pinpoint/web/authorization/controller/AgentInfoController.java#L176-L200","documentation":"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).","triggerScenarios":"GET /isAvailableAgentId for an id that an agent has already registered with data present at System.currentTimeMillis().","commonSituations":"Reinstalling/reusing an old agentId without cleanup; two agents configured with the same id; testing id availability for an id that's actively running.","solutions":["Choose a different, unique agentId","Remove/purge the old agent's data or wait for it to be deactivated before reuse","Treat the 500 as 'id taken' and pick another candidate"],"exampleFix":"// before\nif (available(id)) register(id);\n// after\nif (http.get(\"/isAvailableAgentId?agentId=\" + id).status == 200) register(id);\nelse id = id + \"-\" + uniqueSuffix;","handlingStrategy":"validation","validationCode":"boolean taken = api.getAgentInfo(agentId, System.currentTimeMillis()) != null; if (taken) throw new IllegalStateException(\"agentId already exists: \" + agentId);","typeGuard":null,"tryCatchPattern":"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; }","preventionTips":["Generate unique agent ids per host/instance (suffix with process id)","Never reuse an agentId while its old data is still active","Call this availability endpoint before every new agent registration"],"tags":["rest-api","identifier","conflict","agent-id"],"backgroundTag":"file-already-exists","analyzedSha":"744c3d3075e595656abb1ae331ad2c0e4c9eb996","analyzedAt":"2026-09-07T18:48:45.289Z","contentChangedAt":"2026-09-07T18:48:45.289Z","schemaVersion":2},"datasetVersion":"2026-09-17T15:17:12.973Z"}