apache/pulsar · error · IOException

Failed to get schema ledger for${key}

Error message

Failed to get schema ledger for${key}

What it means

BookkeeperSchemaStorage.getSchemaLedgerList(key) reads the schema locator for a topic's schema key to find the schema data ledgers. If obtaining the locator fails (the async getLocator future completes exceptionally), it logs a warning with the key and rethrows as IOException("Failed to get schema ledger for" + key) — note the message has a cosmetic missing space before the key. This is an I/O-level failure reaching schema storage (BookKeeper/metastore), not a 'schema does not exist' result (that returns null).

Source

Thrown at pulsar-broker/src/main/java/org/apache/pulsar/broker/service/schema/BookkeeperSchemaStorage.java:207

            }
            return Pair.of(locator, list);
        });
    }

    CompletableFuture<Optional<LocatorEntry>> getLocator(String key) {
        return getSchemaLocator(getSchemaPath(key));
    }

    public List<Long> getSchemaLedgerList(String key) throws IOException {
        Optional<LocatorEntry> locatorEntry = null;
        try {
            locatorEntry = getLocator(key).get();
        } catch (Exception e) {
            log.warn()
                    .attr("key", key)
                    .exceptionMessage(e)
                    .log("Failed to get list of schema-storage ledger");
            throw new IOException("Failed to get schema ledger for" + key);
        }
        LocatorEntry entry = locatorEntry.orElse(null);
        if (entry == null) {
            return null;
        }
        List<Long> ledgerIds = new ArrayList<>(entry.locator.getIndexsCount());
        for (int i = 0; i < entry.locator.getIndexsCount(); i++) {
            ledgerIds.add(entry.locator.getIndexAt(i).getPosition().getLedgerId());
        }
        return ledgerIds;
    }

    @VisibleForTesting
    BookKeeper getBookKeeper() {
        return bookKeeper;
    }

    @Override

View on GitHub (pinned to 820761864e)

Solutions

1. Inspect the log warning 'Failed to get list of schema-storage ledger' (attr key, exceptionMessage) for the root cause
2. Verify BookKeeper and metadata-store (ZooKeeper) connectivity/health from the broker
3. Retry the schema read — transient BK/ZK faults often clear; the caller sees IOException so retry/backoff is appropriate
4. If persistent, check the schema-storage ledger metadata for the key and restore from backup or re-register the schema

Example fix

// before
try {
    ledgerIds = storage.getSchemaLedgerList(key);
} catch (IOException e) {
    log.error("giving up: {}", e.getMessage()); // 'Failed to get schema ledger forKey'
}
// after
try {
    ledgerIds = storage.getSchemaLedgerList(key);
} catch (IOException e) {
    log.warn("schema storage unavailable for {}, will retry", key, e);
    ledgerIds = retryWithBackoff(() -> storage.getSchemaLedgerList(key), 3);
}

// pre-check storage availability before schema reads
if (!bkClient.getOwnedLedgersReadyToRead() /* or metadata store healthcheck */) {
    throw new IOException("schema storage backend unavailable");
}

try {
    List<Long> ledgerIds = storage.getSchemaLedgerList(key);
} catch (IOException e) {
    if (e.getMessage() != null && e.getMessage().startsWith("Failed to get schema ledger for")) {
        // transient BK/ZK fault — retry with backoff; check the warn log 'Failed to get list of schema-storage ledger' for root cause
        ledgerIds = retryWithBackoff(() -> storage.getSchemaLedgerList(key), 3, Duration.ofSeconds(1));
    } else {
        throw e;
    }
}

When it happens

Trigger: Calling getSchemaLedgerList (directly or via schemaLedgerId) when the underlying getLocator(key).get() future fails — BookKeeper client unavailable, ZooKeeper/metadata store errors, timeouts, or the schema storage ledger handle is broken.

Common situations: BookKeeper/ZooKeeper outage or network partition on the broker; schema storage metadata corrupted or deleted; timeouts under load; topic namespace whose schema storage was not initialized.

Related errors

• Cursor %s mark-delete position %s is ahead of the last posit
• Timeout during managed ledger close
• Timeout during managed ledger delete operation
• rereplicationEntryBatchSize should be smaller than maxPendin
• Failed to initialize BookKeeper metadata

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