{"record":{"id":"c3c1d41d65a62b4f","repo":"golang/go","slug":"gzip-errheader","errorCode":"gzip.ErrHeader","errorMessage":"gzip: invalid header","messagePattern":"gzip: invalid header","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"error","filePath":"src/compress/gzip/gunzip.go","lineNumber":34,"sourceCode":"\t\"time\"\n)\n\nconst (\n\tgzipID1     = 0x1f\n\tgzipID2     = 0x8b\n\tgzipDeflate = 8\n\tflagText    = 1 << 0\n\tflagHdrCrc  = 1 << 1\n\tflagExtra   = 1 << 2\n\tflagName    = 1 << 3\n\tflagComment = 1 << 4\n)\n\nvar (\n\t// ErrChecksum is returned when reading GZIP data that has an invalid checksum.\n\tErrChecksum = errors.New(\"gzip: invalid checksum\")\n\t// ErrHeader is returned when reading GZIP data that has an invalid header.\n\tErrHeader = errors.New(\"gzip: invalid header\")\n)\n\nvar le = binary.LittleEndian\n\n// noEOF converts io.EOF to io.ErrUnexpectedEOF.\nfunc noEOF(err error) error {\n\tif err == io.EOF {\n\t\treturn io.ErrUnexpectedEOF\n\t}\n\treturn err\n}\n\n// The gzip file stores a header giving metadata about the compressed file.\n// That header is exposed as the fields of the [Writer] and [Reader] structs.\n//\n// Strings must be UTF-8 encoded and may only contain Unicode code points\n// U+0001 through U+00FF, due to limitations of the GZIP file format.\ntype Header struct {","sourceCodeStart":16,"sourceCodeEnd":52,"githubUrl":"https://github.com/golang/go/blob/b6b368adc57c96c3151d224d172029f233ead2c3/src/compress/gzip/gunzip.go#L16-L52","documentation":"Returned when the leading bytes of a candidate GZIP stream fail RFC 1952 header validation: magic bytes must be 0x1f 0x8b, the compression method (CM) must be 8 (deflate), reserved FLG bits must be clear, and the MTIME/XFL/OS fields and any optional FEXTRA/FNAME/FCOMMENT/FHCRC sections must parse cleanly. Any deviation aborts the reader before deflate decoding starts.","triggerScenarios":"Calling gzip.NewReader (or Read on a reset reader) on a stream whose first ten bytes are not a valid GZIP header. Common offenders: feeding raw deflate (no gzip wrapper), feeding zlib, feeding an uncompressed file, or feeding a zip archive whose first entry happens to look binary.","commonSituations":"Pointing the reader at a file with the wrong extension (.gz that is actually plaintext, or a .tar that was never gzipped), double-compression where one layer is stripped, content-encoding negotiation bugs in HTTP clients (server sent identity but client assumed gzip), or reading from a multipart body at the wrong offset.","solutions":["Sniff the first two bytes before wrapping: a real GZIP stream starts with 0x1f 0x8b.","Pick the correct decoder for the actual format: use compress/flate for raw deflate, compress/zlib for zlib, or archive/zip for zip.","If the data is plaintext, drop the gzip wrapper entirely and read the underlying io.Reader directly.","Re-check HTTP Content-Encoding / Transfer-Encoding; many servers omit `gzip` when they send identity responses.","For concatenated streams, loop with Multireader semantics or call Reset between members rather than assuming one header covers everything."],"exampleFix":"// before\ngr, err := gzip.NewReader(resp.Body)\n// \"gzip: invalid header\" on a plaintext response\n\n// after: sniff magic bytes and degrade gracefully\nbr := bufio.NewReader(resp.Body)\nhdr, _ := br.Peek(2)\nvar r io.Reader = br\nif bytes.Equal(hdr, []byte{0x1f, 0x8b}) {\n    gr, err := gzip.NewReader(br)\n    if err != nil { return err }\n    defer gr.Close()\n    r = gr\n}\nio.Copy(out, r)","handlingStrategy":"validation","validationCode":"func isGzipStream(r io.Reader) (io.Reader, bool) {\n    br := bufio.NewReader(r)\n    b, err := br.Peek(2)\n    if err != nil { return br, false }\n    return br, b[0] == 0x1f && b[1] == 0x8b\n}\n\n// Usage:\n//  peeked, ok := isGzipStream(body)\n//  if !ok { /* read raw */ }","typeGuard":null,"tryCatchPattern":"gr, err := gzip.NewReader(r)\nif err != nil {\n    if errors.Is(err, gzip.ErrHeader) {\n        // Fall back to raw read or try other decoders (zlib, flate).\n        return tryOtherFormats(r)\n    }\n    return err\n}","preventionTips":["Always sniff the 0x1f 0x8b magic before wrapping a reader as gzip.","Match Content-Encoding / Content-Type to your decoder choice.","For multipart bodies, parse the part boundary before attempting gzip decode.","Write a unit test that feeds each of {gzip, zlib, raw deflate, plaintext} through your pipeline."],"tags":["gzip","compression","header-validation","file-format","rfc-1952"],"analyzedSha":"b6b368adc57c96c3151d224d172029f233ead2c3","analyzedAt":"2026-08-12T00:22:02.250Z","schemaVersion":2},"datasetVersion":"2026-08-12T06:17:24.410Z"}