{"record":{"id":"12c5650c0341eee3","repo":"kopia/kopia","slug":"error-building-index-shard","errorCode":null,"errorMessage":"error building index shard","messagePattern":"error building index shard","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"repo/content/index/index_builder.go","lineNumber":203,"sourceCode":"\t\tdataShards      []gather.Bytes\n\t\trandomSuffix    [32]byte\n\t)\n\n\tcloseShards := func() {\n\t\tfor _, ds := range dataShardsBuf {\n\t\t\tds.Close()\n\t\t}\n\t}\n\n\tfor _, s := range shardedBuilders {\n\t\tbuf := gather.NewWriteBuffer()\n\n\t\tdataShardsBuf = append(dataShardsBuf, buf)\n\n\t\tif err := s.buildStable(buf, indexVersion); err != nil {\n\t\t\tcloseShards()\n\n\t\t\treturn nil, nil, errors.Wrap(err, \"error building index shard\")\n\t\t}\n\n\t\tif !stable {\n\t\t\tif _, err := rand.Read(randomSuffix[:]); err != nil {\n\t\t\t\tcloseShards()\n\n\t\t\t\treturn nil, nil, errors.Wrap(err, \"error getting random bytes for suffix\")\n\t\t\t}\n\n\t\t\tif _, err := buf.Write(randomSuffix[:]); err != nil {\n\t\t\t\tcloseShards()\n\n\t\t\t\treturn nil, nil, errors.Wrap(err, \"error writing extra random suffix to ensure indexes are always globally unique\")\n\t\t\t}\n\t\t}\n\n\t\tdataShards = append(dataShards, buf.Bytes())\n\t}","sourceCodeStart":185,"sourceCodeEnd":221,"githubUrl":"https://github.com/kopia/kopia/blob/82495e54b584c1ef6073c9e1be048f57f8aef078/repo/content/index/index_builder.go#L185-L221","documentation":"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).","triggerScenarios":"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.","commonSituations":"Flush of pending pack indexes during repository write; misconfigured index version; corrupted or oversized builder contents causing serialization failure.","solutions":["Inspect the wrapped cause (errors.Wrap preserves the inner error) and fix it — most often the index version value.","Verify all entries added to the Builder are valid (IDs and payload data well-formed).","Retry the flush; if persistent, check for version skew between library components writing the index."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"if len(bld) == 0 || (bld.Version != index.Version1 && bld.Version != index.Version2) {\n    return errors.New(\"builder not ready for shard build\")\n}","typeGuard":null,"tryCatchPattern":"shards, _, err := bld.BuildShards(w, stable)\nif err != nil {\n    var cause error\n    errors.As(err, &cause) // inspect wrapped cause to decide on retry vs config fix\n    return err\n}","preventionTips":["Unwrap and log the inner cause — this error is only a wrapper.","Fix the underlying build failure (usually version or malformed entries) rather than retrying blindly."],"tags":["index","serialization","wrapped-error"],"backgroundTag":"internal-invariant-violation","analyzedSha":"82495e54b584c1ef6073c9e1be048f57f8aef078","analyzedAt":"2026-09-07T20:35:21.689Z","contentChangedAt":"2026-09-07T20:35:21.689Z","schemaVersion":2},"datasetVersion":"2026-09-17T15:17:12.973Z"}