apache/pulsar · error · ManagedLedgerException

Timeout during delete-cursors operation

Error message

Timeout during delete-cursors operation

What it means

VALIDATION enforces that managedLedgerOffloadMaxBlockSizeInBytes is at least 5MB (5 * 1024 * 1024), matching most object-storage part/upload minimums, and throws IllegalArgumentException for smaller values. Offload uses multipart/block uploads whose parts must not be below the provider's minimum size.

Source

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

        }
        final Result result = new Result();

        asyncDeleteCursor(name, new DeleteCursorCallback() {
            @Override
            public void deleteCursorComplete(Object ctx) {
                counter.countDown();
            }

            @Override
            public void deleteCursorFailed(ManagedLedgerException exception, Object ctx) {
                result.exception = exception;
                counter.countDown();
            }

        }, null);

        if (!counter.await(AsyncOperationTimeoutSeconds, TimeUnit.SECONDS)) {
            throw new ManagedLedgerException("Timeout during delete-cursors operation");
        }

        if (result.exception != null) {
            log.error().exception(result.exception).log("Deleting cursor");
            throw result.exception;
        }
    }

    @Override
    public ManagedCursor newNonDurableCursor(Position startCursorPosition) throws ManagedLedgerException {
        return newNonDurableCursor(
            startCursorPosition,
            "non-durable-cursor-" + UUID.randomUUID());
    }

    @Override
    public ManagedCursor newNonDurableCursor(Position startPosition, String subscriptionName)
            throws ManagedLedgerException {

View on GitHub (pinned to 820761864e)

Solutions

1. Set managedLedgerOffloadMaxBlockSizeInBytes to at least 5242880 (5MB), e.g. 67108864 (64MB) which is the usual default.
2. If you intended a smaller unit, convert: 10MB = 10485760 bytes.
3. To reduce memory, lower managedLedgerOffloadMemoryBufferSize or other buffers instead of the min block size.

Example fix

// before: broker.conf
managedLedgerOffloadMaxBlockSizeInBytes=1048576  # 1MB -> rejected

// after:
managedLedgerOffloadMaxBlockSizeInBytes=67108864  # 64MB

int minBlock = 5 * 1024 * 1024;
if (config.getMaxBlockSizeInBytes() < minBlock) {
    throw new IllegalStateException("managedLedgerOffloadMaxBlockSizeInBytes must be >= 5242880 (5MB), got " + config.getMaxBlockSizeInBytes());
}

try {
    provider.validate(tieringConfig);
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("cannot be less than 5MB")) {
        log.error("Raise managedLedgerOffloadMaxBlockSizeInBytes to at least 5242880 bytes");
    }
    throw e;
}

When it happens

Trigger: Starting offload with TieredStorageConfiguration.getMaxBlockSizeInBytes() set to a value below 5242880 bytes — e.g. managedLedgerOffloadMaxBlockSizeInBytes=1048576 (1MB).

Common situations: Setting the block size to 1MB or 4MB in broker.conf to try to reduce memory usage or to speed up small-ledger offloads, not realizing the 5MB provider minimum; unit confusion (entering KB instead of bytes).

Understand the failure class

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

Related errors

• Timeout during delete operation
• Timeout during close operation
• Timeout during open-cursor operation
• Timeout during managed ledger terminate
• The '${offloaderName}' offloader does not provide an offload

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