kopia/kopia · error

epoch manager parameters

Error message

epoch manager parameters

What it means

This error wraps a failure from the epoch manager's configured paramProvider (e.getParameters calling e.paramProvider.GetParameters). The epoch manager cannot obtain its runtime Parameters (e.g. Enabled flag, timing windows, retention settings) from the provider, so any refresh or cleanup operation is aborted. It is a pass-through wrapper preserving the provider's underlying cause (context cancellation, network/backend error, etc.).

Solutions

1. Inspect the wrapped cause ('error loading ...' underneath) and fix the paramProvider's backend connectivity or credentials.
2. Verify the context passed to the epoch manager is not cancelled or timing out prematurely; extend the deadline if maintenance runs long.
3. Confirm the parameter provider implementation is registered and returns valid Parameters (Enabled, retention, timing fields).
4. Retry the operation — getParameters is called repeatedly and succeeds once the provider recovers.

Example fix

// before: short-lived context for maintenance
ctx, cancel := context.WithTimeout(parent, 2*time.Second)
err := epochMgr.CleanupMarkers(ctx)

// after: adequate deadline + retry on parameter provider errors
ctx, cancel := context.WithTimeout(parent, 5*time.Minute)
if err := epochMgr.CleanupMarkers(ctx); err != nil && strings.Contains(err.Error(), "epoch manager parameters") {
    time.Sleep(time.Second)
    err = epochMgr.CleanupMarkers(ctx)
}

if ctx.Err() != nil { return fmt.Errorf("context invalid before epoch manager call: %w", ctx.Err()) }

if err := mgr.MaybeAdvanceWriteEpoch(ctx); err != nil {
    if strings.Contains(err.Error(), "epoch manager parameters") {
        // underlying param provider failure; check provider backend health, retry with backoff
    }
    return err
}

When it happens

Trigger: Any call to CleanupMarkers, CleanupSupersededIndexes, refreshLocked, MaybeGenerateRangeCheckpoint, refreshAttemptLocked, or MaybeAdvanceWriteEpoch when paramProvider.GetParameters(ctx) returns an error — e.g. ctx cancelled, backing store unreachable, or provider misconfigured.

Common situations: Parameter store (blob storage / database) temporarily unavailable or credentials expired; context deadline exceeded during long-running maintenance; provider implementation returning errors after a version upgrade changed the parameters source.

Related errors

• can't save policy for
• could not get defined policy for source
• encryption error
• epoch manager
• error building index shard

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

Appendix: source

Thrown at internal/epoch/epoch_manager.go:460

		DeletedTotalSize:   deletedTotalSize,
	}, nil
}

func blobSetWrittenEarlyEnough(replacementSet []blob.Metadata, maxReplacementTime time.Time) bool {
	maxTime := blob.MaxTimestamp(replacementSet)
	if maxTime.IsZero() {
		return false
	}

	// compaction set was written sufficiently long ago to be reliably discovered by all
	// other clients - we can delete uncompacted blobs for this epoch.
	return blob.MaxTimestamp(replacementSet).Before(maxReplacementTime)
}

func (e *Manager) getParameters(ctx context.Context) (*Parameters, error) {
	emp, err := e.paramProvider.GetParameters(ctx)
	if err != nil {
		return nil, errors.Wrap(err, "epoch manager parameters")
	}

	return emp, nil
}

func (e *Manager) refreshLocked(ctx context.Context) error {
	if ctx.Err() != nil {
		return errors.Wrap(ctx.Err(), "refreshLocked")
	}

	p, err := e.getParameters(ctx)
	if err != nil {
		return err
	}

	nextDelayTime := initialRefreshAttemptSleep

	if !p.Enabled {

View on GitHub (pinned to 82495e54b5)