benbjohnson/litestream · error

cannot create replica for restore: %w

Error message

cannot create replica for restore: %w

What it means

NewReplicaFromConfig failed while building the replica client used for the initial restore in restoreIfNeeded. The replica config itself is invalid — bad URL, mutually exclusive fields, or missing required settings such as bucket.

Source

Thrown at cmd/litestream/replicate.go:498

	if _, err := os.Stat(dbPath); !os.IsNotExist(err) {
		slog.Info("database exists, skipping restore", "path", dbPath)
		return nil
	}

	// Get replica config (handles both Replica and Replicas fields)
	var rc *ReplicaConfig
	if dbConfig.Replica != nil {
		rc = dbConfig.Replica
	} else if len(dbConfig.Replicas) > 0 {
		rc = dbConfig.Replicas[0]
	} else {
		return fmt.Errorf("no replica configured for database: %s", dbPath)
	}

	// 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
}

View on GitHub (pinned to 4ed7a308f6)

Solutions

1. Fix the underlying replica config error reported by the wrapped error
2. Validate the replica URL format and required fields

When it happens

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