pinpoint-apm/pinpoint · error · IllegalArgumentException

Invalid node key format:

Error message

Invalid node key format:

What it means

ServerMapHistogramController.newApplication validates the nodeKey against NODE_KEY_VALIDATION_PATTERN before splitting it on the node delimiter. Keys that don't match the expected 'applicationName<delimiter>serviceTypeName' shape are rejected with IllegalArgumentException 'Invalid node key format'.

Solutions

  1. Send the key exactly as 'applicationName^serviceTypeName' (check NODE_DELIMITER_PATTERN for the exact delimiter)
  2. Use the node key value verbatim from a prior map API response instead of constructing it
  3. Verify URL encoding of the delimiter (^ -> %5E if required) is not corrupting the value

Example fix

// before
?fromApplicationNames=myApp&fromServiceTypeCodes=1010  (key passed as "myApp")
// after
nodeKey = "myApp^SPRING_BOOT"; // matches NODE_KEY_VALIDATION_PATTERN
Defensive patterns

Strategy: validation

Validate before calling

private static final Pattern KEY = Pattern.compile("^.+\\^.+$");
boolean isValidNodeKey(String key) {
    return key != null && KEY.matcher(key).matches();
}

Type guard

Optional<String> parseNodeKey(String key) {
    return (key != null && key.matches(".+\\^.+")) ? Optional.of(key) : Optional.empty();
}

Try / catch

try {
    app = controller.buildApplication(nodeKey);
} catch (IllegalArgumentException e) {
    if (e.getMessage().startsWith("Invalid node key format")) {
        logger.warn("Malformed node key: {}", nodeKey);
    } else throw e;
}

Prevention

When it happens

Trigger: Passing a node key without the delimiter or extra characters, e.g. 'myApp' (missing '^serviceTypeName'), or containing characters disallowed by the validation pattern.

Common situations: Manual curl calls to the statistics endpoint building keys by hand, URL-encoded delimiter lost or double-encoded, clients echoing back a display label instead of the raw node key.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

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

Appendix: source

Thrown at web/src/main/java/com/navercorp/pinpoint/web/applicationmap/controller/ServerMapHistogramController.java:268

        Range between = Range.between(rangeForm.getFrom(), rangeForm.getTo());
        this.rangeValidator.validate(between);
        return between;
    }

    private SearchOption.Builder searchOptionBuilder() {
        return SearchOption.newBuilder(DEFAULT_MAX_SEARCH_DEPTH);
    }

    private Application getApplication(Service service, ApplicationForm appForm) {
        return applicationValidator.newApplication(service, appForm.getApplicationName(), appForm.getServiceTypeCode(), appForm.getServiceTypeName());
    }

    private Application newApplication(Service service, String nodeKey) {
        if (!StringUtils.hasLength(nodeKey)) {
            throw new IllegalArgumentException("Node key must not be null or empty");
        }
        if (!NODE_KEY_VALIDATION_PATTERN.matcher(nodeKey).matches()) {
            throw new IllegalArgumentException("Invalid node key format: " + nodeKey);
        }
        String[] parts = NODE_DELIMITER_PATTERN.split(nodeKey, 2);
        String applicationName = parts[0];
        String serviceTypeName = parts[1];

        ServiceType serviceType = null;
        if (StringUtils.hasLength(serviceTypeName)) {
            serviceType = registry.findServiceTypeByName(serviceTypeName);
        }
        if (serviceType != null && serviceType.getCode() != ServiceType.UNDEFINED.getCode()) {
            return new Application(service, applicationName, serviceType);
        }
        throw new IllegalArgumentException("Invalid or undefined service type for application: " + nodeKey);
    }

    @GetMapping(value = "/statistics", params = {
            "fromApplicationNames", "fromServiceTypeCodes", "toApplicationNames", "toServiceTypeCodes"
    })

View on GitHub (pinned to 744c3d3075)