thanos-io/thanos · error

reverse symbol lookup

Error message

reverse symbol lookup

What it means

Wrapped error when symbols.ReverseLookup fails for a label name found in the postings table. It means a label name present in the postings offset table is missing from the symbol table — an internal consistency violation of the index file.

Solutions

1. Delete the index-header file so Thanos rebuilds it from the (valid) index
2. Validate the block's index file integrity; re-upload or re-compact the block if corrupt
3. Confirm index-header and index in the bucket belong to the same block ID
4. Restore the block from backup/object versioning

if err != nil && strings.Contains(err.Error(), "reverse symbol lookup") { quarantine/re-upload the block; it is structurally inconsistent }

When it happens

Trigger: During NewBinaryReader, iterating r.postings label names and calling r.symbols.ReverseLookup(k) fails because the name is absent from the symbol table (corrupt or mismatched index sections).

Common situations: Index files assembled from mixed/partial uploads; corruption of the symbol section while postings survive; index-header built from a different index than the one in the bucket.

Understand the failure class

Background: "This is a bug, please report it": internal invariant violations, unreachable panics, and SNH errors explained — this error's family across 47 libraries.

Related errors

• read symbols
• open block
• label names
• empty label set detected for series
• open block

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

Appendix: source

Thrown at pkg/block/indexheader/binary_reader.go:785

			// In worst case we will overfetch a few bytes.
			r.postings[string(lastName)].lastValOffset = r.indexLastPostingEnd - crc32.Size
		}
		// Trim any extra space in the slices.
		for k, v := range r.postings {
			l := make([]postingOffset, len(v.offsets))
			copy(l, v.offsets)
			r.postings[k].offsets = l
		}
	}

	r.nameSymbols = make(map[uint32]string, len(r.postings))
	for k := range r.postings {
		if k == "" {
			continue
		}
		off, err := r.symbols.ReverseLookup(k)
		if err != nil {
			return errors.Wrap(err, "reverse symbol lookup")
		}
		r.nameSymbols[off] = k
	}

	r.dec = &index.Decoder{LookupSymbol: r.LookupSymbol}

	return nil
}

func (r *BinaryReader) IndexVersion() (int, error) {
	return r.indexVersion, nil
}

// PostingsOffsets implements Reader.
func (r *BinaryReader) PostingsOffsets(name string, values ...string) ([]index.Range, error) {
	return r.postingsOffset(name, values...)
}

View on GitHub (pinned to 35b8b99117)