pinpoint-apm/pinpoint · error · InvalidGrpcHeaderException

Invalid +key.name()

Error message

Invalid +key.name()

What it means

InvalidGrpcHeaderException from HeaderExtractor.validateId: an id header value fails IdValidateUtils.validate (bad characters, empty string, or over-length id), so the agent id is rejected before use.

Solutions

1. Use ids composed of allowed characters within AGENT_ID_MAX_LEN
2. Regenerate the agent id if it contains whitespace or special characters
3. Mirror the same validation rules on the agent side before sending

When it happens

Trigger: Thrown at grpc/src/main/java/com/navercorp/pinpoint/grpc/server/HeaderExtractor.java:137 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/e859734af2d79321. Report an issue: GitHub.

Appendix: source

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

                supportCommandCodeList.add(code);
            }
            return supportCommandCodeList;
        } catch (NumberFormatException e) {
            return Header.SUPPORT_COMMAND_CODE_LIST_PARSE_ERROR;
        }
    }

    public boolean getGrpcBuiltInRetry(Metadata headers) {
        final String value = headers.get(Header.GRPC_BUILT_IN_RETRY);
        if (value != null) {
            return Boolean.parseBoolean(value);
        }
        return Header.DEFAULT_GRPC_BUILT_IN_RETRY;
    }

    String validateId(String id, Metadata.Key<?> key) {
        if (!IdValidateUtils.validateId(id, idMaxLength)) {
            throw new InvalidGrpcHeaderException(key, "Invalid " + key.name());
        }
        return id;
    }

    public int getServiceType(Metadata headers) {
        final String serviceTypeStr = headers.get(Header.SERVICE_TYPE_KEY);
        if (serviceTypeStr == null) {
            return ServiceType.UNDEFINED.getCode();
        }
        try {
            return Integer.parseInt(serviceTypeStr);
        } catch (NumberFormatException ignored) {
            return ServiceType.UNDEFINED.getCode();
        }
    }
}

View on GitHub (pinned to 744c3d3075)