What causes "Error while scanning ledgers for ${namespaceName}" in apache/pulsar?

Check the broker log for 'Error while scanning offloaded ledgers for namespace' to get the wrapped root-cause stack trace.

apache/pulsar · error · RestException

Error while scanning ledgers for ${namespaceName}

Error message

Error while scanning ledgers for ${namespaceName}

What it means

Top-level error handler of the namespace offloaded-ledger scan endpoint: any Throwable escaping while preparing or running the scan is converted into HTTP 500 with message 'Error while scanning ledgers for <namespace>'. Unlike the streaming-lambda case, this fires before/beside streaming and gives the caller a clean (but opaque) 500 with the namespace name.

Source

Thrown at pulsar-broker/src/main/java/org/apache/pulsar/broker/admin/v2/Namespaces.java:3631

                            out.append("\"errors\": " + errors + ",\n");
                            out.append("\"unknown\": " + unknown + "\n");
                        }
                    });
                    out.append("}");
                    out.flush();
                    outputStream.flush();
                } catch (Exception err) {
                    log.error().exception(err).log("error");
                    throw new RuntimeException(err);
                }
            };
            return Response.ok(output).type(MediaType.APPLICATION_JSON_TYPE).build();
        } catch (Throwable err) {
            log.error()
                    .attr("namespace", namespaceName)
                    .exception(err)
                    .log("Error while scanning offloaded ledgers for namespace");
            throw new RestException(Response.Status.INTERNAL_SERVER_ERROR,
                    "Error while scanning ledgers for " + namespaceName);
        }
    }

    @GET
    @Path("/{tenant}/{namespace}/entryFilters")
    @Operation(summary = "Get maxConsumersPerSubscription config on a namespace.")
    @ApiResponses(value = {
            @ApiResponse(responseCode = "200", description = "Get maxConsumersPerSubscription config on a namespace.",
                    content = @Content(schema = @Schema(implementation = EntryFilters.class))),
            @ApiResponse(responseCode = "403", description = "Don't have admin permission"),
            @ApiResponse(responseCode = "404", description = "Namespace does not exist") })
    public void getEntryFiltersPerTopic(
            @Suspended final AsyncResponse asyncResponse,
            @PathParam("tenant") String tenant,
            @PathParam("namespace") String namespace) {
        validateNamespaceName(tenant, namespace);
        validateNamespacePolicyOperationAsync(namespaceName, PolicyName.ENTRY_FILTERS, PolicyOperation.READ)

View on GitHub (pinned to 820761864e)

Solutions

Check the broker log for 'Error while scanning offloaded ledgers for namespace' to get the wrapped root-cause stack trace.
Verify the BookKeeper/metadata service (e.g. ZooKeeper) is healthy and reachable from the broker.
Confirm the requesting user has superuser/namespace read permissions and that the namespace exists; then retry the scan.

Defensive patterns

Strategy: try-catch

Validate before calling

// pre-check permissions and namespace existence before scanning
admin.namespaces().getPolicies(tenant + "/" + namespace); // throws 403/404 early if unavailable

Try / catch

try {
    return admin.namespaces().getTiDBLedgers(tenant, namespace);
} catch (PulsarAdminException e) {
    log.error("Offloaded ledger scan failed for {}/{}: {}", tenant, namespace, e.getMessage());
    // check broker-side root cause: metadata service health, offload config, permissions
    throw e;
}

Prevention

Monitor ZooKeeper/metadata service health; most 500s here stem from metadata read failures.
Grant the caller superuser or adequate namespace read permissions before scanning.
Grep broker logs for 'Error while scanning offloaded ledgers for namespace' to identify the wrapped cause.

When it happens

Trigger: GET /admin/v2/namespaces/{tenant}/{namespace}/tiDBLedgers when the initial scan setup fails — typically inability to read ledgers from the metadata service, authorization failure, or metadata inconsistency for the namespace.

Common situations: BookKeeper metadata service (ZooKeeper) unreachable or session expired; ledgers referenced by topics already deleted from metadata; offload driver misconfiguration; insufficient permissions on the namespace.

Related errors

AI-assisted analysis of apache/pulsar@820761864e (2026-09-06). Data as JSON: /api/errors/5712703518a2a431. Report an issue: GitHub.