{"record":{"id":"e3240a718f8c12cd","repo":"grpc/grpc-go","slug":"extproc-input-metadata-is-nil","errorCode":null,"errorMessage":"extproc: input metadata is nil","messagePattern":"extproc: input metadata is nil","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/xds/httpfilter/extconfig.go","lineNumber":120,"sourceCode":"// key and value, and checks if the mutation is permitted by the AllowExpr and\n// DisallowExpr regular expressions.\n//\n// The following headers are always ignored:\n// - Pseudo-headers (keys starting with ':').\n// - The 'host' header.\n// - Headers with non-lowercase keys.\n// - Headers with keys or values exceeding 16384 bytes.\n//\n// If a mutation is disallowed and DisallowIsError is true, an error is\n// returned. Otherwise, the disallowed mutation is silently ignored.\n//\n// The input metadata must not be nil.\nfunc (hmr *HeaderMutationRules) ApplyAdditions(hvos []*v3corepb.HeaderValueOption, input metadata.MD) error {\n\tif hmr == nil {\n\t\thmr = &HeaderMutationRules{}\n\t}\n\tif input == nil {\n\t\treturn fmt.Errorf(\"extproc: input metadata is nil\")\n\t}\n\tif hmr.DisallowAll {\n\t\treturn nil\n\t}\n\n\tfor _, hvo := range hvos {\n\t\theader := hvo.GetHeader()\n\t\tkey := header.GetKey()\n\t\tif len(key) == 0 || key[0] == ':' || key == \"host\" || key != strings.ToLower(key) || len(key) > 16384 {\n\t\t\tcontinue\n\t\t}\n\n\t\tvalue := header.GetValue()\n\t\tif strings.HasSuffix(key, \"-bin\") {\n\t\t\tvalue = string(header.GetRawValue())\n\t\t}\n\t\tif len(value) > 16384 {\n\t\t\tcontinue","sourceCodeStart":102,"sourceCodeEnd":138,"githubUrl":"https://github.com/grpc/grpc-go/blob/03255a9237b6eb32710f6bc4f2de9a675b99fe36/internal/xds/httpfilter/extconfig.go#L102-L138","documentation":"Raised by (*HeaderMutationRules).ApplyAdditions (extconfig.go:120) when the input metadata argument is nil. The method's contract (documented at extconfig.go:114 'The input metadata must not be nil') requires a non-nil metadata.MD to mutate; a nil input is a programmer error in the caller. In the shipped filter, ApplyAdditions is called from extproc applyMutations (ext_proc.go:1377) with the stream's metadata, which is expected to be non-nil.","triggerScenarios":"ApplyAdditions is invoked with input == nil. In production this means the filter implementation passed a nil metadata.MD into applyMutations; in tests/tools it means a direct caller forgot to allocate metadata before calling.","commonSituations":"A direct unit test of HeaderMutationRules passes nil for the metadata; a custom filter integration that constructs a HeaderMutationRules and calls ApplyAdditions on a response path where no metadata was received yet; a regression in the extproc stream handling that fails to lazily initialize metadata.","solutions":["Ensure the metadata.MD passed to ApplyAdditions is always initialized — use metadata.MD{} (or the actual received headers) rather than a nil map.","If you call applyMutations/ApplyAdditions directly, allocate md := metadata.MD{} before the call when no real headers exist.","For extproc, confirm the stream path that reached applyMutations actually obtained outgoing/incoming metadata; a nil there indicates an upstream initialization bug to file against gRPC."],"exampleFix":"// before\nvar md metadata.MD         // nil map\nerr := hmr.ApplyAdditions(setHeaders, md)\n\n// after\nmd := metadata.MD{}       // non-empty, mutable map\nerr := hmr.ApplyAdditions(setHeaders, md)","handlingStrategy":"validation","validationCode":"// Guard the ApplyAdditions contract (extconfig.go:119-121).\nfunc safeApplyAdditions(hmr *httpfilter.HeaderMutationRules, hvos []*v3corepb.HeaderValueOption, md metadata.MD) error {\n    if md == nil {\n        md = metadata.MD{} // never pass nil; method requires non-nil input\n    }\n    return hmr.ApplyAdditions(hvos, md)\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Always initialize metadata (even as metadata.MD{}) before passing to ApplyAdditions/applyMutations.","Treat 'input metadata must not be nil' as a hard precondition — add a nil check in calling code.","If you call applyMutations in a custom integration, ensure the metadata was actually received first."],"tags":["grpc","xds","ext-proc","header-mutation","nil-check"],"analyzedSha":"03255a9237b6eb32710f6bc4f2de9a675b99fe36","analyzedAt":"2026-08-07T00:29:34.215Z","schemaVersion":2},"datasetVersion":"2026-08-07T03:17:09.362Z"}