{"record":{"id":"5dbb7a7f7c5e0923","repo":"thanos-io/thanos","slug":"unknown-index-header-file-version-d","errorCode":null,"errorMessage":"unknown index header file version %d","messagePattern":"unknown index header file version (.+?)","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/block/indexheader/binary_reader.go","lineNumber":682,"sourceCode":"\tstart := time.Now()\n\n\tdefer func() {\n\t\tr.metrics.loadDuration.Observe(time.Since(start).Seconds())\n\t}()\n\t// Verify header.\n\tif r.b.Len() < headerLen {\n\t\treturn errors.Wrap(encoding.ErrInvalidSize, \"index header's header\")\n\t}\n\tif m := binary.BigEndian.Uint32(r.b.Range(0, 4)); m != MagicIndex {\n\t\treturn errors.Errorf(\"invalid magic number %x\", m)\n\t}\n\tr.version = int(r.b.Range(4, 5)[0])\n\tr.indexVersion = int(r.b.Range(5, 6)[0])\n\n\tr.indexLastPostingEnd = int64(binary.BigEndian.Uint64(r.b.Range(6, headerLen)))\n\n\tif r.version != BinaryFormatV1 {\n\t\treturn errors.Errorf(\"unknown index header file version %d\", r.version)\n\t}\n\n\tr.toc, err = newBinaryTOCFromByteSlice(r.b)\n\tif err != nil {\n\t\treturn errors.Wrap(err, \"read index header TOC\")\n\t}\n\n\t// TODO(bwplotka): Consider contributing to Prometheus to allow specifying custom number for symbolsFactor.\n\tr.symbols, err = index.NewSymbols(r.b, r.indexVersion, int(r.toc.Symbols))\n\tif err != nil {\n\t\treturn errors.Wrap(err, \"read symbols\")\n\t}\n\n\tvar lastName, lastValue []byte\n\tif r.indexVersion == index.FormatV1 {\n\t\t// Earlier V1 formats don't have a sorted postings offset table, so\n\t\t// load the whole offset table into memory.\n\t\tr.postingsV1 = map[string]map[string]index.Range{}","sourceCodeStart":664,"sourceCodeEnd":700,"githubUrl":"https://github.com/thanos-io/thanos/blob/35b8b991177def87ed52dcf10f9b6d87f07282c8/pkg/block/indexheader/binary_reader.go#L664-L700","documentation":"The binary index-header carries a format version byte; the reader only understands BinaryFormatV1. This error is returned when the version byte read from the header is anything other than 1, i.e., the file was written by an unknown future (or bogus) format.","triggerScenarios":"Loading a binary index-header whose version byte (offset 4) is not BinaryFormatV1 — e.g., a cache file produced by a newer Thanos that bumped the format, or random bytes being misread as an index-header.","commonSituations":"Rolling upgrade/downgrade of store-gateways sharing a persistent cache volume written by a different format version; corrupted cache where a version byte got flipped; mixing Thanos forks with divergent formats.","solutions":["Clear the shared cache directory (delete cached .index-header files) so they are regenerated in the format this binary supports.","Run matching Thanos versions across all instances sharing the same cache volume.","If in the bucket, re-upload index-headers generated by a compatible version.","Verify file integrity if the version byte looks randomly corrupted."],"exampleFix":"null","handlingStrategy":"validation","validationCode":"b, err := os.ReadFile(hdrPath)\nif err == nil && len(b) >= 5 && int(b[4]) != BinaryFormatV1 {\n    os.Remove(hdrPath) // unknown version; clear so it is regenerated in v1\n}","typeGuard":"func isSupportedIndexHeaderVersion(b []byte) bool {\n    return len(b) >= 5 && int(b[4]) == BinaryFormatV1\n}","tryCatchPattern":"r, err := NewBinaryReader(ctx, logger, bkt, dir, id, sampling, metrics)\nif err != nil && strings.Contains(err.Error(), \"unknown index header file version\") {\n    // shared cache written by incompatible version; purge and rebuild\n    purgeIndexHeaderCache(dir)\n    return NewBinaryReader(ctx, logger, bkt, dir, id, sampling, metrics)\n}","preventionTips":["Run the same Thanos version on all instances sharing a persistent cache.","Purge cache directories after version upgrades/downgrades.","Pin Thanos versions in deployments touching shared volumes.","Validate the version byte before adopting pre-existing cache files."],"tags":["version","index-header","compatibility","format"],"backgroundTag":"unsupported-enum-value","analyzedSha":"35b8b991177def87ed52dcf10f9b6d87f07282c8","analyzedAt":"2026-09-07T01:49:59.689Z","contentChangedAt":"2026-09-07T01:49:59.689Z","schemaVersion":2},"datasetVersion":"2026-09-15T23:17:13.987Z"}