{"record":{"id":"372c60c863d6c7c8","repo":"apache/pulsar","slug":"managedledgerexception-wrapped-from-err-in-offloa","errorCode":null,"errorMessage":"ManagedLedgerException (wrapped from err in OffloadedLedgerMetadataConsumer)","messagePattern":"ManagedLedgerException \\(wrapped from err in OffloadedLedgerMetadataConsumer\\)","errorType":"exception","errorClass":"ManagedLedgerException","httpStatus":null,"severity":"error","filePath":"tiered-storage/jcloud/src/main/java/org/apache/bookkeeper/mledger/offload/jcloud/impl/BlobStoreManagedLedgerOffloader.java","lineNumber":773,"sourceCode":"                    .uuid(contextUuid)\n                    .ledgerId(ledgerId != null ? ledgerId : -1)\n                    .lastModified(lastModified != null ? lastModified.getTime() : 0)\n                    .size(size != null ? size : -1)\n                    .uri(uri != null ? uri.toString() : null)\n                    .userMetadata(userMetadata != null ? userMetadata : Collections.emptyMap())\n                    .build();\n            try {\n                boolean canContinue = consumer.accept(offloadedLedgerMetadata);\n                if (!canContinue) {\n                    log.info(\"Iteration stopped by the OffloadedLedgerMetadataConsumer\");\n                    return null;\n                }\n            } catch (Exception err) {\n                log.error().exception(err).log(\"Error in OffloadedLedgerMetadataConsumer\");\n                if (err instanceof InterruptedException) {\n                    Thread.currentThread().interrupt();\n                }\n                throw ManagedLedgerException.getManagedLedgerException(err);\n            }\n        }\n        log.info().attr(\"nextMarker\", pages.getNextMarker()).log(\"Page scan complete\");\n        return pages.getNextMarker();\n    }\n\n}\n","sourceCodeStart":755,"sourceCodeEnd":781,"githubUrl":"https://github.com/apache/pulsar/blob/820761864ed8e2a7d2e52dd9763ad2ae117c1395/tiered-storage/jcloud/src/main/java/org/apache/bookkeeper/mledger/offload/jcloud/impl/BlobStoreManagedLedgerOffloader.java#L755-L781","documentation":"During getOffloadPoliciesBacklog / metadata page scans, BlobStoreManagedLedgerOffloader iterates offloaded-ledger metadata pages with a consumer. If the consumer (OffloadedLedgerMetadataConsumer) throws for any reason, the exception is logged and re-wrapped via ManagedLedgerException.getManagedLedgerException(err) so it surfaces as a ManagedLedgerException to managed-ledger callers.","triggerScenarios":"A page-scan consumer (listing offloaded ledger metadata in the blob store) throws — storage client errors, parse errors in the consumer's handling, or InterruptedException while waiting — and the loop catches Exception and converts it.","commonSituations":"Listing objects in an S3/GCS bucket fails (credentials, throttling, network); consumer logic bug while processing offload metadata; broker shutdown interrupting the scan.","solutions":["Read the wrapped cause (ManagedLedgerException#getCause) to find the real storage/processing failure and fix it","Verify blob-store list permissions and connectivity for the offload bucket","For InterruptedException, restore the interrupt and retry after the broker's shutdown completes","Retry the scan/backlog operation once the storage backend is healthy"],"exampleFix":"// caller\ntry { offloader.scanOffloadedLedgers(marker, consumer); }\ncatch (ManagedLedgerException mle) {\n  log.warn(\"scan failed: {}\", mle.getCause()); // look here for root cause\n}","handlingStrategy":"try-catch","validationCode":"// preflight: confirm the offload bucket is listable\nListObjectsV2Request req = new ListObjectsV2Request()\n    .withBucketName(offloadBucket).withMaxKeys(1);\ns3Client.listObjectsV2(req); // fails fast on perms/creds/network","typeGuard":null,"tryCatchPattern":"try {\n  offloader.scanOffloadedLedgers(marker, consumer);\n} catch (ManagedLedgerException e) {\n  Throwable root = rootCause(e);\n  if (root instanceof InterruptedException) {\n    Thread.currentThread().interrupt(); // honor shutdown\n  } else {\n    log.error(\"offload metadata scan failed: {}\", String.valueOf(root));\n  }\n}","preventionTips":["Always inspect getCause() of ManagedLedgerException for the real error","Verify bucket list permissions and connectivity for the offloader","Wrap consumer bodies to avoid throwing mid-scan; collect errors instead","Preserve interrupt status on shutdown"],"tags":["tiered-storage","object-storage","managed-ledger"],"backgroundTag":"managed-ledger-offload-error","analyzedSha":"820761864ed8e2a7d2e52dd9763ad2ae117c1395","analyzedAt":"2026-09-06T00:14:20.138Z","contentChangedAt":"2026-09-06T00:14:20.138Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}