{"record":{"id":"8501bfc110b1dd40","repo":"benbjohnson/litestream","slug":"failed-to-configure-replica-for-s-w","errorCode":null,"errorMessage":"failed to configure replica for %s: %w","messagePattern":"failed to configure replica for (.+?): %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cmd/litestream/main.go","lineNumber":909,"sourceCode":"\t\tmetaPathCopy := filepath.Join(baseMetaDir, relPath+litestream.MetaDirSuffix)\n\t\tdbConfigCopy.MetaPath = &metaPathCopy\n\t\tdbConfigCopy.MetaDir = nil\n\tcase dbc.MetaPath != nil:\n\t\tbaseMetaPath, err := expand(*dbc.MetaPath)\n\t\tif err != nil {\n\t\t\treturn nil, fmt.Errorf(\"failed to expand meta path for %s: %w\", dbPath, err)\n\t\t}\n\t\tmetaPathCopy := deriveMetaPathForDirectoryEntry(baseMetaPath, relPath)\n\t\tdbConfigCopy.MetaPath = &metaPathCopy\n\t\tdbConfigCopy.MetaDir = nil\n\t}\n\n\t// Deep copy replica config and make path unique per database.\n\t// This prevents all databases from writing to the same replica path.\n\tif dbc.Replica != nil {\n\t\treplicaCopy, err := cloneReplicaConfigWithRelativePath(dbc.Replica, relPath)\n\t\tif err != nil {\n\t\t\treturn nil, fmt.Errorf(\"failed to configure replica for %s: %w\", dbPath, err)\n\t\t}\n\t\tdbConfigCopy.Replica = replicaCopy\n\t}\n\n\t// Also handle deprecated 'replicas' array field.\n\tif len(dbc.Replicas) > 0 {\n\t\tdbConfigCopy.Replicas = make([]*ReplicaConfig, len(dbc.Replicas))\n\t\tfor i, replica := range dbc.Replicas {\n\t\t\treplicaCopy, err := cloneReplicaConfigWithRelativePath(replica, relPath)\n\t\t\tif err != nil {\n\t\t\t\treturn nil, fmt.Errorf(\"failed to configure replica %d for %s: %w\", i, dbPath, err)\n\t\t\t}\n\t\t\tdbConfigCopy.Replicas[i] = replicaCopy\n\t\t}\n\t}\n\n\treturn NewDBFromConfig(&dbConfigCopy)\n}","sourceCodeStart":891,"sourceCodeEnd":927,"githubUrl":"https://github.com/benbjohnson/litestream/blob/4ed7a308f6271ebfd2b0a6e4b70b03011a37e4a3/cmd/litestream/main.go#L891-L927","documentation":"Each discovered database gets a deep copy of the replica config with its path made unique (suffixed with the database's relative path) so databases don't overwrite each other in the replica destination. If cloneReplicaConfigWithRelativePath fails to derive that unique path, the error is wrapped with the database path.","triggerScenarios":"cloneReplicaConfigWithRelativePath(dbc.Replica, relPath) returns an error for a specific database — e.g. the replica (bucket/path) URL cannot be parsed or extended with the relative path suffix.","commonSituations":"Invalid replica URL format in the config; replica path template that can't accept the appended relative path; unusual characters in a database's relative path breaking URL joining.","solutions":["Check the replica URL syntax in the config (e.g. s3://bucket/prefix) and fix it.","Inspect the wrapped inner error for the exact parse/join failure and the offending db path.","Rename the database file to avoid problematic characters in its relative path.","Verify the replica config is valid by testing it against a single-DB (non-directory) setup."],"exampleFix":"# before\nreplica:\n  url: s3:bucket/db   # malformed\n\n# after\nreplica:\n  url: s3://mybucket/litestream","handlingStrategy":"validation","validationCode":"u, err := url.Parse(replicaURL)\nif err != nil || u.Scheme == \"\" {\n    return fmt.Errorf(\"invalid replica url %q\", replicaURL)\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Validate replica URLs (scheme://bucket/prefix) before enabling directory replication.","Test the same replica config against a single-DB setup first.","Avoid special characters in database filenames that break URL path joining."],"tags":["litestream","replica","config","url"],"backgroundTag":"invalid-url","analyzedSha":"4ed7a308f6271ebfd2b0a6e4b70b03011a37e4a3","analyzedAt":"2026-09-06T18:29:25.564Z","contentChangedAt":"2026-09-06T18:29:25.564Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}