{"record":{"id":"5991f8412b38accb","repo":"kopia/kopia","slug":"error-compacting-single-epoch","errorCode":null,"errorMessage":"error compacting single epoch","messagePattern":"error compacting single epoch","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"repo/maintenance/maintenance_run.go","lineNumber":364,"sourceCode":"}\n\nfunc runTaskEpochAdvance(ctx context.Context, em *epoch.Manager, runParams RunParameters, s *Schedule) error {\n\treturn reportRunAndMaybeCheckContentIndex(ctx, runParams.rep, TaskEpochAdvance, s, func() (maintenancestats.Kind, error) {\n\t\tuserLog(ctx).Info(\"Advancing epoch markers...\")\n\n\t\tstats, err := em.MaybeAdvanceWriteEpoch(ctx)\n\n\t\treturn stats, errors.Wrap(err, \"error advancing epoch marker\")\n\t})\n}\n\nfunc runTaskEpochMaintenanceQuick(ctx context.Context, em *epoch.Manager, runParams RunParameters, s *Schedule) error {\n\terr := reportRunAndMaybeCheckContentIndex(ctx, runParams.rep, TaskEpochCompactSingle, s, func() (maintenancestats.Kind, error) {\n\t\tuserLog(ctx).Info(\"Compacting an eligible uncompacted epoch...\")\n\n\t\tstats, err := em.MaybeCompactSingleEpoch(ctx)\n\n\t\treturn stats, errors.Wrap(err, \"error compacting single epoch\")\n\t})\n\tif err != nil {\n\t\treturn err\n\t}\n\n\terr = runTaskEpochAdvance(ctx, em, runParams, s)\n\n\treturn errors.Wrap(err, \"error to advance epoch in quick epoch maintenance task\")\n}\n\nfunc runTaskEpochMaintenanceFull(ctx context.Context, runParams RunParameters, s *Schedule) error {\n\tem, hasEpochManager, emerr := runParams.rep.ContentManager().EpochManager(ctx)\n\tif emerr != nil {\n\t\treturn errors.Wrap(emerr, \"epoch manager\")\n\t}\n\n\tif !hasEpochManager {\n\t\treturn nil","sourceCodeStart":346,"sourceCodeEnd":382,"githubUrl":"https://github.com/kopia/kopia/blob/82495e54b584c1ef6073c9e1be048f57f8aef078/repo/maintenance/maintenance_run.go#L346-L382","documentation":"Wraps a failure from epoch.Manager.MaybeCompactSingleEpoch, which compacts the content index of one eligible uncompacted epoch into a single index blob. Emitted from runTaskEpochMaintenanceQuick when single-epoch compaction fails. The wrapped inner error identifies the actual storage or index failure.","triggerScenarios":"During quick epoch maintenance, MaybeCompactSingleEpoch is invoked and fails while reading the epoch's uncompacted index blobs, merging them, or writing/committing the compacted index blob.","commonSituations":"Corrupt or missing index blob in storage; network interruption mid-compaction; concurrent maintenance racing on the same epoch; storage quota exceeded when writing the merged index.","solutions":["Read the wrapped root cause to distinguish read vs. write vs. commit failures.","Run kopia index recover / index optimize to repair or rebuild index blobs if corruption is suspected.","Ensure no concurrent maintenance jobs operate on the same repository.","Retry the epoch maintenance task; it is resumable and will re-attempt the epoch."],"exampleFix":null,"handlingStrategy":"retry","validationCode":"// Go: check index integrity before maintenance\nif err := rep.VerifyIndex(ctx); err != nil {\n    return fmt.Errorf(\"run 'kopia index recover' first: %w\", err)\n}","typeGuard":null,"tryCatchPattern":"if err := runMaintenance(ctx); err != nil {\n    if isTransientStorageErr(errors.RootCause(err)) {\n        scheduleRetryWithBackoff()\n    } else {\n        alertOperator(err)\n    }\n}","preventionTips":["Avoid killing maintenance processes mid-compaction.","Set storage quotas high enough for merged index writes.","Run index verification periodically.","Serialize maintenance across all clients."],"tags":["epoch","compaction","index"],"backgroundTag":"database-write-failed","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"}