multiple orca load reports found in provided metadata

Error message

multiple orca load reports found in provided metadata

What it means

Returned by ToLoadReport when the gRPC trailer/response metadata contains more than one value for the ORCA load-report key "endpoint-load-metrics-bin". The ORCA protocol expects at most one binary-encoded OrcaLoadReport per call; multiple values indicate a malformed/interleaved report and the function refuses to guess which one to use.

Source

Thrown at orca/internal/internal.go:64

// transmitted.
const TrailerMetadataKey = "endpoint-load-metrics-bin"

// ToLoadReport unmarshals a binary encoded [ORCA LoadReport] protobuf message
// from md and returns the corresponding struct. The load report is expected to
// be stored as the value for key "endpoint-load-metrics-bin".
//
// If no load report was found in the provided metadata, if multiple load
// reports are found, or if the load report found cannot be parsed, an error is
// returned.
//
// [ORCA LoadReport]: (https://github.com/cncf/xds/blob/main/xds/data/orca/v3/orca_load_report.proto#L15)
func ToLoadReport(md metadata.MD) (*v3orcapb.OrcaLoadReport, error) {
	vs := md.Get(TrailerMetadataKey)
	if len(vs) == 0 {
		return nil, nil
	}
	if len(vs) != 1 {
		return nil, errors.New("multiple orca load reports found in provided metadata")
	}
	ret := new(v3orcapb.OrcaLoadReport)
	if err := proto.Unmarshal([]byte(vs[0]), ret); err != nil {
		return nil, fmt.Errorf("failed to unmarshal load report found in metadata: %v", err)
	}
	return ret, nil
}

View on GitHub (pinned to 0c51461d27)

Solutions

Find the component that appends "endpoint-load-metrics-bin" twice and ensure it is added exactly once per RPC.
De-duplicate the metadata before calling ToLoadReport (keep the first/last bytewise value).
If you intentionally merged metadata from multiple backends, split the reports and parse each separately.
Update the offending interceptor/balancer to use metadata.Append only when the key is absent.

Example fix

// before
func handle(md metadata.MD) {
    rpt, _ := orcainternal.ToLoadReport(md) // md has 2 values for endpoint-load-metrics-bin
}
// after: ensure single append on the producer side, or de-dup on the consumer side
func handle(md metadata.MD) {
    vs := md.Get(orcainternal.TrailerMetadataKey)
    if len(vs) > 1 { md.Set(orcainternal.TrailerMetadataKey, vs[len(vs)-1]) }
    rpt, _ := orcainternal.ToLoadReport(md)
}

Defensive patterns

Strategy: try-catch

Validate before calling

// De-duplicate ORCA trailer values before parsing.
func sanitizeORCAMetadata(md metadata.MD) metadata.MD {
    vs := md.Get(orcainternal.TrailerMetadataKey)
    if len(vs) > 1 {
        md.Set(orcainternal.TrailerMetadataKey, vs[len(vs)-1]) // keep the last report
    }
    return md
}

Try / catch

if _, err := orcainternal.ToLoadReport(md); err != nil { if strings.Contains(err.Error(), "multiple orca load reports") { md = sanitizeORCAMetadata(md); rpt, err = orcainternal.ToLoadReport(md) }; if err != nil { /* record metric, continue without ORCA data */ } }

Prevention

Never call metadata.Append for the ORCA trailer more than once per RPC.
When merging metadata across hops, dedup binary-valued keys before forwarding.
In test harnesses, assert exactly one endpoint-load-metrics-bin value per call.

When it happens

Trigger: Calling orca/internal.ToLoadReport(md) on a metadata.MD where md.Get("endpoint-load-metrics-bin") returns a slice of length > 1. Can happen if a server/interceptor appends the trailer twice, or if metadata from multiple backends is merged incorrectly.

Common situations: A custom balancer/interceptor copies ORCA trailers across hop boundaries and double-appends. Aggregating metadata from several sub-streams into one metadata.MD without de-duplication. A buggy server adds the trailer both in headers and trailers.

Related errors

AI-assisted analysis of grpc/grpc-go@0c51461d27 (2026-08-11). Data as JSON: /api/errors/36109e2284ebcb3e. Report an issue: GitHub.