What causes "failed to load index entries for v0 index entry" in kopia/kopia?

Note the inner BlobID error and inspect/repair that specific index blob.

failed to load index entries for v0 index entry

Error message

failed to load index entries for v0 index entry

What it means

After listing blobs for both index generations, validateAction calls loadIndexBlobs for the v0 set (which=0). Any error returned by the per-blob loading is re-wrapped with this message, so this is the v0-side wrapper around failures like error 516 (failed to load index blob with BlobID X).

Solutions

Note the inner BlobID error and inspect/repair that specific index blob.
Run index maintenance (`kopia index optimize`) or index rebuild before upgrading.
Restore from backup and retry the upgrade.
Proceed only after validate passes — never force an upgrade with a broken v0 index.

Defensive patterns

Strategy: validation

Validate before calling

// pre-check the v0 index layer before upgrade validation
if err := checkIndexLayerConsistency(ctx, rep, /* v0 */ 0); err != nil {
    return fmt.Errorf("v0 index layer unhealthy; run index maintenance first: %w", err)
}

Try / catch

if err := upgradeValidate(ctx, rep); err != nil && strings.Contains(err.Error(), "failed to load index entries for v0 index entry") {
    log.Fatalf("legacy (v0) index is damaged — repair index or restore from backup before upgrading: %v", err)
}

Prevention

Never force an upgrade while the v0 index fails validation.
Schedule regular `kopia index optimize` to keep index layers healthy.
Upgrade only from clean backups taken immediately before the attempt.
Investigate the inner per-BlobID error before retrying.

When it happens

Trigger: Running `repository upgrade validate` when the v0 loadIndexBlobs pass fails — one or more old-generation index blobs cannot be loaded or decoded.

Common situations: Legacy repositories with corrupt v0 index blobs, interrupted historical index writes, object-store degradation, or upgrading a repository that was never fully consistent at the v0 layer.

Understand the failure class

Background: "failed to read file", EACCES, ENOENT and "could not read <path>" errors: when a program can't read a file from disk — this error's family across 49 libraries.

Related errors

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

Appendix: source

Thrown at cli/command_repository_upgrade.go:148

		return errors.Wrapf(err, "failed to list index blobs for old index")
	}

	indexBlobInfos1, err := sm.IndexReaderV1().ListIndexBlobInfos(ctx)
	if err != nil {
		log(ctx).Errorf("failed to list index blobs for new index. upgrade may have failed.: %v", err)
		return nil
	}

	if len(indexBlobInfos0) == 0 && len(indexBlobInfos1) > 0 {
		log(ctx).Info("old index is empty (possibly due to upgrade), nothing to compare against")
		return nil
	}

	// load index blobs into their appropriate positions inside the indexEntries map

	err = loadIndexBlobs(ctx, indexEntries, sm, 0, indexBlobInfos0)
	if err != nil {
		return errors.Wrapf(err, "failed to load index entries for v0 index entry")
	}

	err = loadIndexBlobs(ctx, indexEntries, sm, 1, indexBlobInfos1)
	if err != nil {
		return errors.Wrapf(err, "failed to load index entries for new index")
	}

	var msgs []string // a place to keep messages from the index comparison process

	var zeroInfo content.Info

	// both indexes will have matching contentIDs with matching indexInfo structures.
	//nolint:gocritic
	for contentID, indexEntryPairs := range indexEntries {
		iep0 := indexEntryPairs[0] // first entry of index entry pair
		iep1 := indexEntryPairs[1] // second entry of index entry pair

		// check that both the new and old indexes have entries for the same content

View on GitHub (pinned to 82495e54b5)