benbjohnson/litestream · error

sync replica for %s: %w

Error message

sync replica for %s: %w

What it means

ReplicateCommand.runOnce failed to sync the database's replica, i.e. uploading pending LTX files to remote storage failed. The wrapped error usually comes from the replica client's WriteLTXFile and indicates a storage backend I/O, auth, or connectivity problem during one-shot replication.

Source

Thrown at cmd/litestream/replicate.go:409

// runOnce performs one-shot replication for all databases.
// It syncs all databases, optionally takes snapshots, and enforces retention.
func (c *ReplicateCommand) runOnce(ctx context.Context) {
	var err error
	defer func() { c.execCh <- err }()

	for _, db := range c.Store.DBs() {
		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

View on GitHub (pinned to 4ed7a308f6)

Solutions

1. Inspect the wrapped error for the backend-specific cause (S3/GCS/ABS/NATS)
2. Verify credentials and network access to the replica destination
3. Re-run the one-shot replicate command; successfully-synced files are skipped on retry

When it happens

Trigger: Thrown at cmd/litestream/replicate.go:409 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/76de930f0733abaf. Report an issue: GitHub.