{"record":{"id":"34a3d897e8d08167","repo":"benbjohnson/litestream","slug":"open-remote-l0-file-w","errorCode":null,"errorMessage":"open remote L0 file: %w","messagePattern":"open remote L0 file: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"db.go","lineNumber":1627,"sourceCode":"\tdb.Logger.Info(\"detected database behind replica\",\n\t\t\"db_txid\", dbPos.TXID,\n\t\t\"replica_txid\", replicaInfo.MaxTXID)\n\n\t// Clear local L0 files\n\tl0Dir := db.LTXLevelDir(0)\n\tif err := os.RemoveAll(l0Dir); err != nil && !os.IsNotExist(err) {\n\t\treturn fmt.Errorf(\"remove L0 directory: %w\", err)\n\t}\n\tdb.invalidatePosCache()\n\tif err := internal.MkdirAll(l0Dir, db.dirInfo); err != nil {\n\t\treturn fmt.Errorf(\"recreate L0 directory: %w\", err)\n\t}\n\n\t// Fetch latest L0 LTX file from replica\n\tminTXID, maxTXID := replicaInfo.MinTXID, replicaInfo.MaxTXID\n\treader, err := db.Replica.Client.OpenLTXFile(ctx, 0, minTXID, maxTXID, 0, 0)\n\tif err != nil {\n\t\treturn fmt.Errorf(\"open remote L0 file: %w\", err)\n\t}\n\tdefer func() { _ = reader.Close() }()\n\n\t// Write to temp file and atomically rename\n\tlocalPath := db.LTXPath(0, minTXID, maxTXID)\n\ttmpPath := localPath + \".tmp\"\n\n\ttmpFile, err := os.Create(tmpPath)\n\tif err != nil {\n\t\treturn fmt.Errorf(\"create temp L0 file: %w\", err)\n\t}\n\tdefer func() { _ = os.Remove(tmpPath) }() // Clean up temp file on error\n\n\tif _, err := io.Copy(tmpFile, reader); err != nil {\n\t\t_ = tmpFile.Close()\n\t\treturn fmt.Errorf(\"copy L0 file: %w\", err)\n\t}\n","sourceCodeStart":1609,"sourceCodeEnd":1645,"githubUrl":"https://github.com/benbjohnson/litestream/blob/4ed7a308f6271ebfd2b0a6e4b70b03011a37e4a3/db.go#L1609-L1645","documentation":"After recreating the L0 directory, Litestream opens the remote L0 LTX file on the replica via db.Replica.Client.OpenLTXFile(ctx, 0, minTXID, maxTXID, 0, 0). This error wraps any failure to open that remote object, meaning the snapshot source file cannot be read from storage.","triggerScenarios":"checkDatabaseBehindReplica calls OpenLTXFile for level 0 with the replica's MinTXID..MaxTXID range and the storage client returns an error — object not found (the exact LTX file vanished from the bucket), 403 on GET, network failure mid-request, or unsupported/nil client.","commonSituations":"Retention/lifecycle rules deleted the remote L0 file between the MaxLTXFileInfo listing and the GET; wrong bucket/path after a config change; credentials allow listing but not reading (S3 s3:GetObject missing); transient object-store outage.","solutions":["Read the wrapped cause: a 404/NoSuchKey means the file disappeared (check bucket lifecycle/retention rules); 403 means missing read permission.","Restore read permissions (s3:GetObject / Storage Object Viewer) for the replica credentials.","If a lifecycle policy deletes L0 files, disable it or align retention so files referenced by Min/MaxTXID still exist.","Retry — many object-store failures are transient; the next sync re-runs the behind-check."],"exampleFix":"// before: S3 policy allows List only\n{\"Effect\":\"Allow\",\"Action\":[\"s3:ListBucket\"],\"Resource\":[\"arn:aws:s3:::mybucket\"]}\n// after: also allow object reads\n{\"Effect\":\"Allow\",\"Action\":[\"s3:GetObject\"],\"Resource\":[\"arn:aws:s3:::mybucket/*\"]}","handlingStrategy":"retry","validationCode":"// Verify the remote object is readable before relying on it\nout, err := s3Client.GetObject(&s3.GetObjectInput{Bucket: b, Key: k})\nif err != nil { log.Printf(\"remote LTX unreadable: %v\", err) }","typeGuard":"null","tryCatchPattern":"reader, err := client.OpenLTXFile(ctx, 0, minTXID, maxTXID, 0, 0)\nif err != nil {\n    var nf *ltx.NoSuchFileError\n    if errors.As(err, &nf) { log.Printf(\"LTX file missing from replica: %v\", err) }\n    return err // litestream retries on next sync\n}","preventionTips":["Grant s3:GetObject (or equivalent) to the replica credentials","Disable bucket lifecycle rules that could delete LTX files litestream still needs","Keep litestream versions and replica layout compatible","Monitor storage provider health/status pages"],"tags":["litestream","replica","object-storage","network","ltx"],"backgroundTag":"resource-not-found","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"}