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'.

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)

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 pattern([a-zA-Z0-9._\-]+)
• Invalid applicationName
• ${fieldName} too long:${name.length()}
• sqlUid length must be 16: ${sqlUid.length}
• invalid applicationName=${applicationName}

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