benbjohnson/litestream · error

enforce retention for %s: %w

Error message

enforce retention for %s: %w

What it means

ReplicateCommand.runOnce failed to enforce snapshot retention (Store.EnforceSnapshotRetention) with -enforce-retention. The retention pass lists and deletes old LTX files on the replica; failure is a backend list/delete error or corrupted replica state.

Source

Thrown at cmd/litestream/replicate.go:426

		if err = db.Replica.Sync(ctx); err != nil {
			err = fmt.Errorf("sync replica for %s: %w", db.Path(), err)
			return
		}

		// Force a snapshot if requested.
		if c.forceSnapshot {
			slog.Info("taking snapshot", "path", db.Path())
			if _, err = db.Snapshot(ctx); err != nil {
				err = fmt.Errorf("snapshot %s: %w", db.Path(), err)
				return
			}
		}

		// Enforce retention if requested.
		if c.enforceRetention {
			slog.Info("enforcing retention", "path", db.Path())
			if err = c.Store.EnforceSnapshotRetention(ctx, db); err != nil {
				err = fmt.Errorf("enforce retention for %s: %w", db.Path(), err)
				return
			}
		}
	}

	slog.Info("one-shot replication complete")
}

// Close closes all open databases.
func (c *ReplicateCommand) Close(ctx context.Context) error {
	for _, monitor := range c.directoryMonitors {
		monitor.Close()
	}
	c.directoryMonitors = nil

	if c.Server != nil {
		if err := c.Server.Close(); err != nil {
			slog.Error("error closing control server", "error", err)

View on GitHub (pinned to 4ed7a308f6)

Solutions

1. Check the wrapped backend error for list/delete permission issues
2. Verify retention configuration values are sane
3. Retry the replicate run

When it happens

Trigger: Thrown at cmd/litestream/replicate.go:426 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of benbjohnson/litestream@4ed7a308f6 (2026-09-06). Data as JSON: /api/errors/22eb329b820ddc92. Report an issue: GitHub.