pinpoint-apm/pinpoint · error · InvalidGrpcHeaderException

Invalid +idKey.name()

Error message

Invalid +idKey.name()

What it means

InvalidGrpcHeaderException from HeaderExtractor.getName: the name header exists but fails IdValidateUtils.checkId (illegal characters, empty value, or trailing whitespace), so the supplied name is rejected.

Solutions

1. Send agent names matching the documented charset/length rules
2. Trim and validate names client-side before attaching the header
3. Increase maxNameLength if legitimate long names are being cut

When it happens

Trigger: Thrown at grpc/src/main/java/com/navercorp/pinpoint/grpc/server/HeaderExtractor.java:74 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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

Appendix: source

Thrown at grpc/src/main/java/com/navercorp/pinpoint/grpc/server/HeaderExtractor.java:74

    public String getId(Metadata headers, Metadata.Key<String> idKey) {
        final String id = headers.get(idKey);
        if (id == null) {
            throw new InvalidGrpcHeaderException(idKey, idKey.name() + " header is missing");
        }
        return validateId(id, idKey);
    }

    public String getName(Metadata headers, Metadata.Key<String> idKey) {
        return getName(headers, idKey, this.nameMaxLength);
    }

    public String getName(Metadata headers, Metadata.Key<String> idKey, int maxNameLength) {
        final String name = headers.get(idKey);
        if (!StringUtils.isEmpty(name)) {
            final IdValidateUtils.CheckResult result = IdValidateUtils.checkId(name, defaultLength(maxNameLength, this.nameMaxLength));
            if (result == IdValidateUtils.CheckResult.FAIL_PATTERN) {
                throw new InvalidGrpcHeaderException(idKey, "Invalid " + idKey.name());
            }
            if (result == IdValidateUtils.CheckResult.FAIL_LENGTH) {
                throw new InvalidGrpcHeaderException(idKey, "Invalid " + idKey.name() + ".length");
            }
        }
        return name;
    }

    private int defaultLength(int length, int defaultValue) {
        if (length != UNSPECIFIED_LENGTH) {
            return length;
        }
        return defaultValue;
    }

    public long getSocketId(Metadata headers) {
        final String socketIdStr = headers.get(Header.SOCKET_ID);
        if (socketIdStr == null) {

View on GitHub (pinned to 744c3d3075)