{"record":{"id":"e9a89062e325a8c3","repo":"benbjohnson/litestream","slug":"poll-l0-w","errorCode":null,"errorMessage":"poll L0: %w","messagePattern":"poll L0: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"vfs.go","lineNumber":2609,"sourceCode":"// pollReplicaClient fetches new LTX files from the replica client and updates\n// the page index & the current position.\nfunc (f *VFSFile) pollReplicaClient(ctx context.Context) error {\n\tpos := f.Pos()\n\tf.logger.Debug(\"polling replica client\", \"txid\", pos.TXID.String())\n\n\tcombined := make(map[uint32]ltx.PageIndexElem)\n\n\tf.mu.Lock()\n\tbaseCommit := f.commit\n\tmaxTXID1Snapshot := f.maxTXID1\n\tf.mu.Unlock()\n\n\tnewCommit := baseCommit\n\treplaceIndex := false\n\n\tmaxTXID0, idx0, commit0, replace0, err := f.pollLevel(ctx, 0, pos.TXID, baseCommit)\n\tif err != nil {\n\t\treturn fmt.Errorf(\"poll L0: %w\", err)\n\t}\n\tif replace0 {\n\t\treplaceIndex = true\n\t\tbaseCommit = commit0\n\t\tnewCommit = commit0\n\t\tcombined = idx0\n\t} else {\n\t\tif len(idx0) > 0 {\n\t\t\tbaseCommit = commit0\n\t\t}\n\t\tfor k, v := range idx0 {\n\t\t\tcombined[k] = v\n\t\t}\n\t\tif commit0 > newCommit {\n\t\t\tnewCommit = commit0\n\t\t}\n\t}\n","sourceCodeStart":2591,"sourceCodeEnd":2627,"githubUrl":"https://github.com/benbjohnson/litestream/blob/4ed7a308f6271ebfd2b0a6e4b70b03011a37e4a3/vfs.go#L2591-L2627","documentation":"Wrapper around a failure in pollLevel(level=0) while the VFS background poller fetches new L0 (transaction-level) LTX files from the replica storage client. The wrapped error is the underlying ReplicaClient failure (listing or opening LTX files).","triggerScenarios":"Periodic pollReplicaClient call; client.LTXFiles(ctx, 0, ...) fails due to network errors, credentials expiry, bucket not found, or storage API errors.","commonSituations":"S3/blob storage outages or throttling during polling; revoked IAM credentials; misconfigured replica client after environment changes; DNS/network failures in containers.","solutions":["Read the wrapped error to identify the storage client failure","Verify replica credentials and bucket/container configuration","Check network connectivity / storage endpoint reachability from the host","Retry after transient failures — the poller retries on the next PollInterval tick; use litestream reset if local LTX state is corrupted"],"exampleFix":null,"handlingStrategy":"retry","validationCode":"// pre-flight storage check before opening the VFS\niter, err := client.LTXFiles(ctx, 0, 1, false)\nif err != nil {\n    return fmt.Errorf(\"replica storage unavailable: %w\", err)\n}\niter.Close()","typeGuard":null,"tryCatchPattern":"if err := pollOnce(ctx); err != nil {\n    var netErr net.Error\n    if errors.As(err, &netErr) || isRetryablePageError(err) {\n        time.Sleep(backoff)\n        return pollOnce(ctx)\n    }\n    return err\n}","preventionTips":["Monitor litestream logs for recurring 'cannot fetch new ltx files' errors","Rotate credentials before expiry","Alert on storage client error rates"],"tags":["storage","replication","polling"],"backgroundTag":"network-request-failed","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"}