What causes "header not found" in thanos-io/thanos?

Verify the input begins with the expected codecHeaderStreamedSnappy bytes before decoding

header not found

Error message

header not found

What it means

A generic guard in the decoder: the input bytes do not start with the streamed-snappy codec magic header (codecHeaderStreamedSnappy), so diffVarintSnappyStreamedDecode refuses the input. Either the data is not encoded postings at all, or it was written by an older Thanos using the non-streamed codec variant.

Solutions

Verify the input begins with the expected codecHeaderStreamedSnappy bytes before decoding
Purge/rebuild the affected postings cache entries
Check writer/reader Prometheus version compatibility

Example fix

// before
d, err := diffVarintSnappyStreamedDecode(b, false)
// after
if !isDiffVarintSnappyStreamedEncodedPostings(b) {
    return fmt.Errorf("not streamed snappy postings, len=%d", len(b))
}
d, err := diffVarintSnappyStreamedDecode(b, false)

Defensive patterns

Strategy: validation

Validate before calling

func isStreamedSnappyPostings(b []byte) bool {
    return bytes.HasPrefix(b, codecHeaderStreamedSnappy)
}

Type guard

func asStreamedSnappyPostings(b []byte) ([]byte, bool) {
    if !bytes.HasPrefix(b, codecHeaderStreamedSnappy) { return nil, false }
    return b[len(codecHeaderStreamedSnappy):], true
}

Try / catch

p, err := diffVarintSnappyStreamedDecode(b, false)
if err != nil {
    if err.Error() == "header not found" {
        return nil, errCorruptCacheEntry // evict and refetch from index
    }
    return nil, err
}

Prevention

Dispatch decoders only after checking the magic header (as decodePostings does)
Purge cache entries with missing/truncated headers
Keep writer and reader Prometheus versions compatible

When it happens

Trigger: Calling diffVarintSnappyStreamedDecode (via decodePostings) with input failing isDiffVarintSnappyStreamedEncodedPostings — wrong decoder dispatch, truncated header, or non-streamed codec bytes.

Common situations: Version mismatch between cache writer and reader; hand-crafted or corrupted cache entries; truncation of the first bytes of a postings blob.

Understand the failure class

Background: Checksum mismatch errors: "checksum verification failed", "digest mismatch", "expected vs actual checksum" — what they mean and how to fix them — this error's family across 41 libraries.

Related errors

AI-assisted analysis of thanos-io/thanos@35b8b99117 (2026-09-07). Data as JSON: /api/errors/e7b2fce7ad4c834f. Report an issue: GitHub.

Appendix: source

Thrown at pkg/store/postings_codec.go:136

		} else if written != uvarintSize {
			return nil, errors.Wrap(err, "short-write for uvarint encoded byte")
		}

		prev = v
	}
	if p.Err() != nil {
		return nil, p.Err()
	}
	if err := sw.Close(); err != nil {
		return nil, errors.Wrap(err, "closing snappy stream writer")
	}

	return compressedBuf.Bytes(), nil
}

func diffVarintSnappyStreamedDecode(input []byte, disablePooling bool) (closeablePostings, error) {
	if !isDiffVarintSnappyStreamedEncodedPostings(input) {
		return nil, errors.New("header not found")
	}

	return newStreamedDiffVarintPostings(input[len(codecHeaderStreamedSnappy):], disablePooling)
}

type streamedDiffVarintPostings struct {
	curSeries storage.SeriesRef

	err               error
	input, buf        []byte
	maximumDecodedLen int

	db *encoding.Decbuf

	readSnappyIdentifier bool
	disablePooling       bool
}

View on GitHub (pinned to 35b8b99117)