{"record":{"id":"3ce3984036e350ea","repo":"benbjohnson/litestream","slug":"no-replica-client-configured-set-litestream-repli","errorCode":null,"errorMessage":"no replica client configured: set LITESTREAM_REPLICA_URL, use SetVFSConfig, or pass replica_url in the database URI","messagePattern":"no replica client configured: set LITESTREAM_REPLICA_URL, use SetVFSConfig, or pass replica_url in the database URI","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"vfs.go","lineNumber":174,"sourceCode":"\tvar perConnClient bool\n\tif cfg != nil && cfg.ReplicaURL != \"\" {\n\t\tclient, err = NewReplicaClientFromURL(cfg.ReplicaURL)\n\t\tif err != nil {\n\t\t\treturn nil, 0, fmt.Errorf(\"create per-connection replica client: %w\", err)\n\t\t}\n\t\tif err := client.Init(context.Background()); err != nil {\n\t\t\tif closer, ok := client.(io.Closer); ok {\n\t\t\t\tif closeErr := closer.Close(); closeErr != nil {\n\t\t\t\t\treturn nil, 0, fmt.Errorf(\"init per-connection replica client: %w\", errors.Join(err, closeErr))\n\t\t\t\t}\n\t\t\t}\n\t\t\treturn nil, 0, fmt.Errorf(\"init per-connection replica client: %w\", err)\n\t\t}\n\t\tperConnClient = true\n\t}\n\n\tif client == nil {\n\t\treturn nil, 0, fmt.Errorf(\"no replica client configured: set LITESTREAM_REPLICA_URL, use SetVFSConfig, or pass replica_url in the database URI\")\n\t}\n\n\tf := NewVFSFile(client, name, vfs.logger.With(\"name\", name))\n\tf.PollInterval = vfs.PollInterval\n\tf.CacheSize = vfs.CacheSize\n\tf.vfs = vfs\n\tf.perConnClient = perConnClient\n\n\tif cfg != nil {\n\t\tif cfg.PollInterval != nil {\n\t\t\tf.PollInterval = *cfg.PollInterval\n\t\t}\n\t\tif cfg.CacheSize != nil {\n\t\t\tf.CacheSize = *cfg.CacheSize\n\t\t}\n\t}\n\n\twriteEnabled := vfs.WriteEnabled","sourceCodeStart":156,"sourceCodeEnd":192,"githubUrl":"https://github.com/benbjohnson/litestream/blob/4ed7a308f6271ebfd2b0a6e4b70b03011a37e4a3/vfs.go#L156-L192","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"// before\ndb, err := sql.Open(\"sqlite\", \"file:app.db?vfs=litestream\") // no replica source configured\n\n// after\nlitestream.SetVFSConfig(&litestream.VFSConfig{ReplicaURL: \"s3://my-bucket/app.db\"})\ndb, err := sql.Open(\"sqlite\", \"file:app.db?vfs=litestream\")","handlingStrategy":"validation","validationCode":"func requireReplicaSource(cfg *litestream.VFSConfig) error {\n    if cfg != nil && cfg.ReplicaURL != \"\" { return nil }\n    if os.Getenv(\"LITESTREAM_REPLICA_URL\") != \"\" { return nil }\n    return errors.New(\"no replica configured: set LITESTREAM_REPLICA_URL or call SetVFSConfig\")\n}","typeGuard":null,"tryCatchPattern":"db, err := sql.Open(\"sqlite\", dsn)\nif err != nil && strings.Contains(err.Error(), \"no replica client configured\") {\n    return fmt.Errorf(\"startup misconfiguration: %w\", err)\n}","preventionTips":["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"],"tags":["vfs","configuration","missing-config","replica-client"],"backgroundTag":"missing-required-config","analyzedSha":"4ed7a308f6271ebfd2b0a6e4b70b03011a37e4a3","analyzedAt":"2026-09-06T18:29:25.564Z","contentChangedAt":"2026-09-06T18:29:25.564Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}