kopia/kopia · error

error optimizing indexes

Error message

error optimizing indexes

What it means

`kopia index optimize` failed when rep.ContentManager().CompactIndexes returned an error while compacting/merging index blobs according to the provided options (drop-deleted ages, max-concurrency, etc.). The repository's index compaction transaction failed and no useful result was produced.

Solutions

1. Stop other kopia clients that may be writing indexes concurrently, then re-run optimize.
2. Retry with reduced concurrency (e.g. --max-concurrency=1) to avoid storage contention.
3. Check the storage backend for write errors, quota, or permission problems and fix those first.
4. Upgrade kopia if repository format is newer than the CLI; run `kopia repository status` to compare versions.

Example fix

// before
kopia index optimize --max-concurrency=16
// after
kopia index optimize --max-concurrency=1  # avoid contention with concurrent writers

// refuse to optimize while other clients may be writing
if activeWriters := checkOtherKopiaClients(); activeWriters > 0 {
    return fmt.Errorf("%d kopia clients active; retry optimize later", activeWriters)
}

_, err = rep.ContentManager().CompactIndexes(ctx, opt)
if err != nil {
    return errors.Wrap(err, "error optimizing indexes")
}

When it happens

Trigger: Running `kopia index optimize` (runOptimizeCommand) where CompactIndexes fails: concurrent index writers blocking compaction, storage write errors while uploading the merged index blob, deletion of source blobs failing, or invalid optimization options.

Common situations: Another kopia client (backup/sync) running concurrently against the same repository; read-only or quota-exceeded storage backend; very large index blobs timing out during merge; version mismatch between CLI and repository format.

Related errors

• error copying blobs
• error copying
• error deleting index blob
• error deleting old indexes
• error listing blobs with prefix

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

Appendix: source

Thrown at cli/command_index_optimize.go:53

	contentIDs, err := toContentIDs(c.optimizeDropContents)
	if err != nil {
		return err
	}

	opt := indexblob.CompactOptions{
		MaxSmallBlobs: c.optimizeMaxSmallBlobs,
		AllIndexes:    c.optimizeAllIndexes,
		DropContents:  contentIDs,
	}

	if age := c.optimizeDropDeletedOlderThan; age > 0 {
		opt.DropDeletedBefore = rep.Time().Add(-age)
	}

	_, err = rep.ContentManager().CompactIndexes(ctx, opt)

	return errors.Wrap(err, "error optimizing indexes")
}

View on GitHub (pinned to 82495e54b5)