benbjohnson/litestream · error

snapshot %s: %w

Error message

snapshot %s: %w

What it means

ReplicateCommand.runOnce failed while forcing a snapshot of the database (db.Snapshot) with -force-snapshot. Snapshot creation reads the full database into a level-Snapshot LTX file; failure typically means a read error on the database file or a replica write error.

Source

Thrown at cmd/litestream/replicate.go:417

		slog.Info("syncing database", "path", db.Path())

		// Sync the database to process any pending WAL changes.
		if err = db.Sync(ctx); err != nil {
			err = fmt.Errorf("sync database %s: %w", db.Path(), err)
			return
		}

		// Sync the replica to upload any pending LTX files.
		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.

View on GitHub (pinned to 4ed7a308f6)

Solutions

1. Check database file readability and disk space
2. Examine the wrapped error for replica client issues
3. Retry after resolving the underlying cause

When it happens

Trigger: Thrown at cmd/litestream/replicate.go:417 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/3490d7b7ca068a5c. Report an issue: GitHub.