pinpoint-apm/pinpoint · warning · ResponseStatusException

length range is 1 ~ 24

Error message

length range is 1 ~ 24

What it means

AgentInfoController.isAvailableAgentId validates a candidate agentId against Pinpoint's agent-id length constraint (1..AGENT_ID_MAX_LEN=24). A FAIL_LENGTH result throws HTTP 400 'length range is 1 ~ 24'.

Solutions

1. Shorten the agentId to 24 characters or fewer (and at least 1)
2. Truncate or hash long hostnames when generating agent ids in the agent config
3. Pre-validate length in the client before calling

Example fix

// before
String agentId = hostname + "-" + app; // often > 24 chars
// after
String agentId = (hostname + "-" + app).substring(0, Math.min(24, hostname.length() + 1 + app.length()));

if (agentId == null || agentId.isEmpty() || agentId.length() > 24) throw new IllegalArgumentException("agentId length must be 1~24");

boolean isValidAgentIdLength(String id) { return id != null && !id.isEmpty() && id.length() <= PinpointConstants.AGENT_ID_MAX_LEN; }

try { return api.isAvailableAgentId(id); } catch (ResponseStatusException e) { if (e.getStatus() == HttpStatus.BAD_REQUEST) return "RETRY_WITH_NEW_ID"; throw e; }

When it happens

Trigger: GET /isAvailableAgentId?agentId=<empty-after-blank-check-or->24-chars> — the id is longer than 24 characters (empty is caught earlier by @NotBlank).

Common situations: Programmatically generated agent ids (hostnames + suffixes) exceeding 24 chars; UUIDs used as agent ids; trailing whitespace pushing length over the limit.

Understand the failure class

Background: "invalid id" errors: invalid identifier format — why libraries reject IDs before lookup, and how to fix them — this error's family across 37 libraries.

Related errors

• Invalid applicationName
• invalid pattern([a-zA-Z0-9._\-]+)
• too long
• invalid applicationName=
• Invalid argument: webhook.url

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

Appendix: source

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

    @PreAuthorize("@naverPermissionEvaluator.hasInspectorPermission(#serviceName.getName(), new com.navercorp.pinpoint.common.server.bo.AgentParam(#agentId, #to))")
    @GetMapping(value = "/getAgentStatusTimeline", params = {"exclude"})
    public InspectorTimeline getAgentStatusTimeline(
            @ServiceParam ServiceName serviceName,
            @RequestParam("applicationName") @NotBlank String applicationName,
            @RequestParam("agentId") @NotBlank String agentId,
            @RequestParam("from") Timestamp from,
            @RequestParam("to") Timestamp to,
            @RequestParam(value = "exclude", defaultValue = "") int[] excludeEventTypeCodes) {
        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)