kopia/kopia · error

error building index shard

Error message

error building index shard

What it means

Wraps any failure returned by buildStable while serializing one index shard into a buffer inside BuildShards. It indicates the in-memory index entries could not be converted into a stable serialized index blob (e.g. version build failure or buffer error).

Solutions

1. Inspect the wrapped cause (errors.Wrap preserves the inner error) and fix it — most often the index version value.
2. Verify all entries added to the Builder are valid (IDs and payload data well-formed).
3. Retry the flush; if persistent, check for version skew between library components writing the index.

if len(bld) == 0 || (bld.Version != index.Version1 && bld.Version != index.Version2) {
    return errors.New("builder not ready for shard build")
}

shards, _, err := bld.BuildShards(w, stable)
if err != nil {
    var cause error
    errors.As(err, &cause) // inspect wrapped cause to decide on retry vs config fix
    return err
}

When it happens

Trigger: BuildShards (invoked by flushPackIndexesLocked during pack flush) calls s.buildStable(buf, indexVersion) and it returns an error — typically because the underlying buildV1/buildV2 serialization failed, such as the unsupported-version error from error 1510.

Common situations: Flush of pending pack indexes during repository write; misconfigured index version; corrupted or oversized builder contents causing serialization failure.

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

• encryption error
• error building index shard
• error loading indexes
• error writing entry
• error writing entry key

AI-assisted analysis of kopia/kopia@82495e54b5 (2026-09-07). Data as JSON: /api/errors/12c5650c0341eee3. Report an issue: GitHub.

Appendix: source

Thrown at repo/content/index/index_builder.go:203

		dataShards      []gather.Bytes
		randomSuffix    [32]byte
	)

	closeShards := func() {
		for _, ds := range dataShardsBuf {
			ds.Close()
		}
	}

	for _, s := range shardedBuilders {
		buf := gather.NewWriteBuffer()

		dataShardsBuf = append(dataShardsBuf, buf)

		if err := s.buildStable(buf, indexVersion); err != nil {
			closeShards()

			return nil, nil, errors.Wrap(err, "error building index shard")
		}

		if !stable {
			if _, err := rand.Read(randomSuffix[:]); err != nil {
				closeShards()

				return nil, nil, errors.Wrap(err, "error getting random bytes for suffix")
			}

			if _, err := buf.Write(randomSuffix[:]); err != nil {
				closeShards()

				return nil, nil, errors.Wrap(err, "error writing extra random suffix to ensure indexes are always globally unique")
			}
		}

		dataShards = append(dataShards, buf.Bytes())
	}

View on GitHub (pinned to 82495e54b5)