benbjohnson/litestream · error

restore failed: %w

Error message

restore failed: %w

What it means

The initial restore attempt in restoreIfNeeded failed with an error other than ErrTxNotAvailable (which is tolerated on first start). The replica could not produce a consistent database — plan calculation, download, or compaction failed.

Source

Thrown at cmd/litestream/replicate.go:511

	}

	// Create replica from config (nil db since we're just restoring)
	r, err := NewReplicaFromConfig(rc, nil)
	if err != nil {
		return fmt.Errorf("cannot create replica for restore: %w", err)
	}

	// Attempt restore
	opt := litestream.NewRestoreOptions()
	opt.OutputPath = dbPath

	slog.Info("attempting restore before replication", "path", dbPath)
	if err := r.Restore(ctx, opt); errors.Is(err, litestream.ErrTxNotAvailable) {
		// No backup exists yet (first start) - this is OK
		slog.Info("no backup found, starting fresh", "path", dbPath)
		return nil
	} else if err != nil {
		return fmt.Errorf("restore failed: %w", err)
	}

	slog.Info("restore completed", "path", dbPath)
	return nil
}

// Usage prints the help screen to STDOUT.
func (c *ReplicateCommand) Usage() {
	fmt.Printf(`
The replicate command starts a server to monitor & replicate databases.
You can specify your database & replicas in a configuration file or you can
replicate a single database file by specifying its path and its replicas in the
command line arguments.

Usage:

	litestream replicate [arguments]

View on GitHub (pinned to 4ed7a308f6)

Solutions

1. Inspect the wrapped error to identify whether planning, download, or decode failed
2. Check replica credentials/connectivity and that backups exist (litestream ltx)
3. Fix the underlying issue and restart so restore is retried

When it happens

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