benbjohnson/litestream · error

no replica configured for database: %s

Error message

no replica configured for database: %s

What it means

restoreIfNeeded found a database path that does not exist on disk but the DB config has neither a Replica nor any Replicas entry to restore it from. Restore-before-replication cannot proceed without a replica definition.

Source

Thrown at cmd/litestream/replicate.go:492

	dbPath, err := expand(dbConfig.Path)
	if err != nil {
		return err
	}

	// Skip if database already exists
	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 {

View on GitHub (pinned to 4ed7a308f6)

Solutions

1. Add a replica (or replicas) section to the database config
2. Or pre-create the database file if no restore is intended

When it happens

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