Send and Read gRPC Metadata Headers (2026)

gRPC metadata headers are not just for passing arbitrary key-value pairs; they’re a core part of the RPC lifecycle, dictating how requests are routed, authenticated, and even how services signal back-pressure.

Let’s see this in action. Imagine a simple gRPC service that echoes back whatever metadata it receives.

// server.go
package main

import (
	"context"
	"fmt"
	"log"
	"net"

	"google.golang.org/grpc"
	"google.golang.org/grpc/metadata"
	pb "your_module_path/your_proto_package" // Replace with your actual import path
)

type server struct{}

func (s *server) EchoMetadata(ctx context.Context, req *pb.EchoRequest) (*pb.EchoResponse, error) {
	md, ok := metadata.FromIncomingContext(ctx)
	if !ok {
		log.Println("No metadata received")
		return &pb.EchoResponse{Message: "No metadata received"}, nil
	}

	response := "Received metadata:\n"
	for key, values := range md {
		response += fmt.Sprintf("%s: %v\n", key, values)
	}
	return &pb.EchoResponse{Message: response}, nil
}

func main() {
	lis, err := net.Listen("tcp", ":50051")
	if err != nil {
		log.Fatalf("failed to listen: %v", err)
	}
	s := grpc.NewServer()
	pb.RegisterYourServiceServer(s, &server{}) // Replace YourServiceServer
	log.Println("Server listening on port 50051")
	if err := s.Serve(lis); err != nil {
		log.Fatalf("failed to serve: %v", err)
	}
}

// client.go
package main

import (
	"context"
	"log"
	"time"

	"google.golang.org/grpc"
	"google.golang.org/grpc/metadata"
	pb "your_module_path/your_proto_package" // Replace with your actual import path
)

func main() {
	conn, err := grpc.Dial("localhost:50051", grpc.WithInsecure()) // Use WithTransportCredentials for secure connections
	if err != nil {
		log.Fatalf("did not connect: %v", err)
	}
	defer conn.Close()
	c := pb.NewYourServiceClient(conn) // Replace YourServiceClient

	ctx, cancel := context.WithTimeout(context.Background(), time.Second)
	defer cancel()

	// Sending metadata
	outMD := metadata.Pairs(
		"x-request-id", "abc-123",
		"user-agent", "my-grpc-client/1.0",
		"custom-header", "some-value",
	)
	ctx = metadata.NewOutgoingContext(ctx, outMD)

	r, err := c.EchoMetadata(ctx, &pb.EchoRequest{Name: "test"})
	if err != nil {
		log.Fatalf("could not greet: %v", err)
	}
	log.Printf("Response: %s", r.GetMessage())
}

In this example, the client explicitly adds x-request-id, user-agent, and custom-header to the outgoing context. The server then retrieves this metadata using metadata.FromIncomingContext and prints it. This demonstrates the fundamental mechanism of passing information alongside the actual RPC payload.

The underlying problem gRPC metadata solves is the need for out-of-band communication during an RPC. Unlike REST headers, which are HTTP-specific, gRPC metadata is a protocol-level construct. This allows it to be used across different transport layers (like HTTP/2) and for features that don’t map neatly to HTTP headers. For instance, content-type is a standard gRPC metadata key, but so are grpc-timeout for controlling server-side deadlines and grpc-trace-bin for distributed tracing.

When you call metadata.NewOutgoingContext(ctx, md), you’re essentially wrapping the existing context.Context with the provided metadata.MD. When the gRPC client library serializes the RPC call, it inspects this context and encodes the metadata into the underlying transport protocol. On the server side, metadata.FromIncomingContext(ctx) extracts these encoded values from the incoming transport frame and reconstructs the metadata.MD object.

The most common mistake developers make is assuming that all metadata sent by the client will be available on the server. However, certain metadata keys are reserved or have specific behaviors. For instance, the grpc-timeout header, if sent by the client, is interpreted by the gRPC runtime to set the server-side deadline for the RPC, not necessarily passed as a raw value to your service logic unless explicitly extracted and handled. Similarly, the content-type metadata is used by the gRPC codec mechanism.

Here’s a less obvious but crucial point: metadata is not guaranteed to be in any specific order when iterated. While the keys are unique, the order in which you receive them from md (when using for key, values := range md) is not deterministic. This means you should always access metadata by its specific key rather than relying on iteration order. For example, always use md.Get("x-request-id") instead of expecting the first element of an iterated list to be your ID.

The next concept to explore is how to set and propagate metadata across multiple gRPC calls, especially when dealing with distributed systems and service meshes.