no replica client configured: set LITESTREAM_REPLICA_URL, us

Error message

no replica client configured: set LITESTREAM_REPLICA_URL, use SetVFSConfig, or pass replica_url in the database URI

What it means

In openMainDB, after any per-connection configuration is applied, Litestream resolves the final replica client from: the per-connection URL, the config set via SetVFSConfig, or the LITESTREAM_REPLICA_URL environment variable. This error is returned when all three sources are empty — no client was ever configured. Litestream throws it because the read-only VFS has no remote source from which to serve database pages.

Source

Thrown at vfs.go:174

	var perConnClient bool
	if cfg != nil && cfg.ReplicaURL != "" {
		client, err = NewReplicaClientFromURL(cfg.ReplicaURL)
		if err != nil {
			return nil, 0, fmt.Errorf("create per-connection replica client: %w", err)
		}
		if err := client.Init(context.Background()); err != nil {
			if closer, ok := client.(io.Closer); ok {
				if closeErr := closer.Close(); closeErr != nil {
					return nil, 0, fmt.Errorf("init per-connection replica client: %w", errors.Join(err, closeErr))
				}
			}
			return nil, 0, fmt.Errorf("init per-connection replica client: %w", err)
		}
		perConnClient = true
	}

	if client == nil {
		return nil, 0, fmt.Errorf("no replica client configured: set LITESTREAM_REPLICA_URL, use SetVFSConfig, or pass replica_url in the database URI")
	}

	f := NewVFSFile(client, name, vfs.logger.With("name", name))
	f.PollInterval = vfs.PollInterval
	f.CacheSize = vfs.CacheSize
	f.vfs = vfs
	f.perConnClient = perConnClient

	if cfg != nil {
		if cfg.PollInterval != nil {
			f.PollInterval = *cfg.PollInterval
		}
		if cfg.CacheSize != nil {
			f.CacheSize = *cfg.CacheSize
		}
	}

	writeEnabled := vfs.WriteEnabled

View on GitHub (pinned to 4ed7a308f6)

Solutions

Set LITESTREAM_REPLICA_URL in the process environment before opening the connection.
Call litestream.SetVFSConfig(&litestream.VFSConfig{ReplicaURL: "s3://bucket/db"}) once at application startup.
Add replica_url to the database URI: file:app.db?vfs=litestream&replica_url=s3://bucket/app.db.
Verify the env var actually reaches your runtime (docker -e, k8s env, serverless config) with a startup check.

Example fix

// before
db, err := sql.Open("sqlite", "file:app.db?vfs=litestream") // no replica source configured

// after
litestream.SetVFSConfig(&litestream.VFSConfig{ReplicaURL: "s3://my-bucket/app.db"})
db, err := sql.Open("sqlite", "file:app.db?vfs=litestream")

Defensive patterns

Strategy: validation

Validate before calling

func requireReplicaSource(cfg *litestream.VFSConfig) error {
    if cfg != nil && cfg.ReplicaURL != "" { return nil }
    if os.Getenv("LITESTREAM_REPLICA_URL") != "" { return nil }
    return errors.New("no replica configured: set LITESTREAM_REPLICA_URL or call SetVFSConfig")
}

Try / catch

db, err := sql.Open("sqlite", dsn)
if err != nil && strings.Contains(err.Error(), "no replica client configured") {
    return fmt.Errorf("startup misconfiguration: %w", err)
}

Prevention

Call litestream.SetVFSConfig once at process startup before any DB open
Fail fast at boot if neither LITESTREAM_REPLICA_URL nor config is present
In containers/serverless, assert env var propagation with a startup check
Prefer passing replica_url explicitly in the URI for multi-database setups

When it happens

Trigger: Opening a database with vfs=litestream while: the URI has no replica_url parameter, SetVFSConfig was never called (or its ReplicaURL is empty), and LITESTREAM_REPLICA_URL is unset in the process environment.

Common situations: Forgetting to call litestream.SetVFSConfig() during library initialization; deploying to an environment where env vars weren't propagated (containers, serverless); copying example connection strings that omit replica_url.

Understand the failure class

Background: "X is required", "must be set", "cannot be empty": the missing-required-config error family, from Vertex AI project/location to WeChat keys — this error's family across 18 libraries.

Related errors

AI-assisted analysis of benbjohnson/litestream@4ed7a308f6 (2026-09-06). Data as JSON: /api/errors/3ce3984036e350ea. Report an issue: GitHub.