pinpoint-apm/pinpoint · error · InvalidGrpcHeaderException

idKey.name()+ header is missing

Error message

idKey.name()+ header is missing

What it means

Thrown by HeaderExtractor.getId when the required agent-id gRPC header is absent entirely (headers.get(idKey) returns null). Unlike getTime's parse failure, the header was never sent, so agent identification cannot proceed. This is a validation guard on the incoming metadata; the faulting input is the missing idKey header, and clients must always populate the agent-id metadata key. Callers such as header-to-string diagnostics propagate this as InvalidGrpcHeaderException.

Source

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

    }

    public long getTime(Metadata headers, Metadata.Key<String> timeKey) {
        final String timeStr = headers.get(timeKey);
        if (timeStr == null) {
            throw new InvalidGrpcHeaderException(timeKey, timeKey.name() + " header is missing");
        }
        try {
            // check number format
            return Long.parseLong(timeStr);
        } catch (NumberFormatException e) {
            throw new IllegalArgumentException("unsupported format");
        }
    }

    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");
            }

View on GitHub (pinned to 744c3d3075)

Solutions

1. Ensure the client attaches all mandatory headers before the RPC call
2. Update the client to the agent version that sends the expected header names
3. Return a clear INVALID_ARGUMENT status to the client on this exception

When it happens

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