apache/pulsar · error · ManagedLedgerException

Timeout during update managedLedger's properties

Error message

Timeout during update managedLedger's properties

What it means

ManagedLedgerImpl.setProperty()/update-properties waits on a latch for the async metadata-store (ZooKeeper) update of the managed ledger's properties map. If the async update callback does not fire within AsyncOperationTimeoutSeconds, this ManagedLedgerException is thrown. The properties update may or may not have been persisted.

Source

Thrown at managed-ledger/src/main/java/org/apache/bookkeeper/mledger/impl/ManagedLedgerImpl.java:4924

        class Result {
            ManagedLedgerException exception = null;
        }
        final Result result = new Result();
        this.asyncUpdateProperties(properties, isDelete, deleteKey, new UpdatePropertiesCallback() {
            @Override
            public void updatePropertiesComplete(Map<String, String> properties, Object ctx) {
                latch.countDown();
            }

            @Override
            public void updatePropertiesFailed(ManagedLedgerException exception, Object ctx) {
                result.exception = exception;
                latch.countDown();
            }
        }, null);

        if (!latch.await(AsyncOperationTimeoutSeconds, TimeUnit.SECONDS)) {
            throw new ManagedLedgerException("Timeout during update managedLedger's properties");
        }

        if (result.exception != null) {
            log.error().exception(result.exception).log("Update managedLedger's properties failed");
            throw result.exception;
        }
    }

    private void asyncUpdateProperties(Map<String, String> properties, boolean isDelete,
        String deleteKey, final UpdatePropertiesCallback callback, Object ctx) {
        if (!metadataMutex.tryLock()) {
            // Defer update for later
            scheduledExecutor.schedule(() -> asyncUpdateProperties(properties, isDelete, deleteKey,
                callback, ctx), 100, TimeUnit.MILLISECONDS);
            return;
        }
        if (isDelete) {
            propertiesMap.remove(deleteKey);

View on GitHub (pinned to 820761864e)

Solutions

1. Check metadata-store (ZooKeeper) health and connectivity; the timeout usually reflects a store-side stall
2. Use the async updateProperties() variant so you aren't bound by the sync latch timeout
3. Retry the update after connectivity is restored and verify the persisted properties via getProperties()
4. Keep the properties payload small to avoid slow metadata writes

Example fix

// before
ml.setProperty(key, value); // sync latch, throws on ZK stall
// after
ml.asyncSetProperty(key, value)
  .thenAccept(v -> log.info("property updated"))
  .exceptionally(ex -> { log.warn("update failed, retrying", ex); return null; });

if (!zkConnected) { deferPropertyUpdate(key, value); return; }

try {
    ml.setProperty(key, value);
} catch (ManagedLedgerException e) {
    log.warn("property update timed out; verify ZK then retry", e);
    retryWithBackoff(() -> ml.asyncSetProperty(key, value));
}

When it happens

Trigger: Calling the synchronous setProperty()/updateProperties API while the metadata store is slow or disconnected — ZooKeeper session expiry, quorum loss, or large properties payload causing slow write.

Common situations: Admin updates of topic properties during a ZooKeeper outage or long GC pause on the broker; network partition between broker and metadata store.

Understand the failure class

• Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

Related errors

• Timeout during managed ledger close
• Timeout during managed ledger delete operation
• Timeout during managed ledger offload operation
• Failed to initialize BookKeeper metadata
• Failed to get children of ${path}

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