{"record":{"id":"2398639940bcfe4a","repo":"kopia/kopia","slug":"error-to-advance-epoch-in-quick-epoch-maintenance","errorCode":null,"errorMessage":"error to advance epoch in quick epoch maintenance task","messagePattern":"error to advance epoch in quick epoch maintenance task","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"repo/maintenance/maintenance_run.go","lineNumber":372,"sourceCode":"\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\n\t}\n\n\t// compact a single epoch\n\tif err := 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","sourceCodeStart":354,"sourceCodeEnd":390,"githubUrl":"https://github.com/kopia/kopia/blob/82495e54b584c1ef6073c9e1be048f57f8aef078/repo/maintenance/maintenance_run.go#L354-L390","documentation":"Wraps the error returned by runTaskEpochAdvance when it is called at the end of runTaskEpochMaintenanceQuick. The single-epoch compaction succeeded but advancing the write epoch marker failed. The message is purely a wrapper; the cause is whatever 'error advancing epoch marker' wrapped.","triggerScenarios":"runTaskEpochMaintenanceQuick (from runQuickMaintenance) runs MaybeCompactSingleEpoch successfully, then calls runTaskEpochAdvance whose MaybeAdvanceWriteEpoch fails, e.g. marker write failure or epoch conflict.","commonSituations":"Two hosts running quick maintenance concurrently; storage throttling or transient outage right after compaction; read-only storage preventing marker update.","solutions":["Inspect errors.RootCause for the epoch-manager failure detail.","Re-run maintenance — the next pass will retry epoch advancement.","Serialize maintenance runs across hosts via the repository's maintenance lock.","Check storage write permissions for the epoch marker prefix."],"exampleFix":null,"handlingStrategy":"retry","validationCode":null,"typeGuard":null,"tryCatchPattern":"if err := rep.Maintenance.Run(ctx, maintenance.ModeQuick); err != nil {\n    log.Printf(\"epoch advance deferred: %v\", err) // next run retries\n}","preventionTips":["Single maintenance owner per repository.","Ensure storage writes are permitted (not read-only mount/credentials).","Back off and retry — compaction succeeded, only marker update failed.","Monitor epoch count growth as a symptom of repeated advancement failure."],"tags":["epoch","maintenance","quick-maintenance"],"backgroundTag":"invalid-state-transition","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"}