thanos-io/thanos · error

create index header reader

Error message

create index header reader

What it means

When syncing a single block, BucketStore builds an index-header reader via indexheader.NewReader (wrapped with "create index header reader"). Failures come from downloading/parsing the block's meta or index-header file from object storage, or from the underlying bucket reader.

Solutions

1. Run `thanos tools bucket verify` to identify and mark/remove the corrupt block.
2. Delete/re-upload the affected block so meta.json and index-header files are complete.
3. Check bucket credentials and network access for GetObject on the block prefix.
4. Upgrade all Thanos components to the same version to avoid index-header format mismatches.

Example fix

// before
// opaque failure: create index header reader: ...
// after
if err := store.InitialSync(ctx); err != nil {
    logger.Error("block sync failed; run `thanos tools bucket verify` to find corrupt blocks", "err", err)
    return err
}

if err := verifyBlockObjects(ctx, bkt, meta.ULID); err != nil {
    return errors.Wrapf(err, "block %s objects incomplete", meta.ULID)
}

if err := syncBlock(ctx, meta); err != nil {
    if isTransient(err) { return retryWithBackoff(ctx, func() error { return syncBlock(ctx, meta) }) }
    return errors.Wrapf(err, "block %s may be corrupt; run bucket verify", meta.ULID)
}

When it happens

Trigger: Syncing a block whose index-header (or index) object is missing, corrupt, or fails checksum; bucket GetObject errors; or binary-format version mismatch between the writer and reader of index-header files.

Common situations: Partially uploaded blocks in the bucket, Thanos version upgrade changing index-header format while old blocks lack header files, or transient object-storage errors during startup.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

• invalid magic number
• write index header
• generate index header
• index header PostingsOffset
• compaction

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

Appendix: source

Thrown at pkg/store/bucket.go:874

			s.metrics.blockLoadDuration.Observe(time.Since(start).Seconds())
		}
	}()
	s.metrics.blockLoads.Inc()

	lset := labels.FromMap(meta.Thanos.Labels)
	h := lset.Hash()

	indexHeaderReader, err := s.indexReaderPool.NewBinaryReader(
		ctx,
		s.logger,
		s.bkt,
		s.dir,
		meta.ULID,
		s.postingOffsetsInMemSampling,
		meta,
	)
	if err != nil {
		return errors.Wrap(err, "create index header reader")
	}
	defer func() {
		if err != nil {
			runutil.CloseWithErrCapture(&err, indexHeaderReader, "index-header")
		}
	}()

	b, err := newBucketBlock(
		ctx,
		s.metrics,
		meta,
		s.bkt,
		dir,
		s.indexCache,
		s.chunkPool,
		indexHeaderReader,
		s.partitioner,
		s.blockEstimatedMaxSeriesFunc,

View on GitHub (pinned to 35b8b99117)