apache/pulsar · error · IOException

it is not a valid hashed path name : ${pathName}

Error message

it is not a valid hashed path name : ${pathName}

What it means

IOException thrown by LongHierarchicalLedgerManager.getLedgerId when the given path does not start with the configured ledgerRootPath, meaning it is not a valid long-hierarchical hashed ledger path and cannot be converted back to a ledger id.

Source

Thrown at pulsar-metadata/src/main/java/org/apache/pulsar/metadata/bookkeeper/LongHierarchicalLedgerManager.java:38

import java.io.IOException;
import java.util.concurrent.ScheduledExecutorService;
import lombok.CustomLog;
import org.apache.bookkeeper.proto.BookkeeperInternalCallbacks;
import org.apache.bookkeeper.util.StringUtils;
import org.apache.pulsar.metadata.api.MetadataStore;
import org.apache.zookeeper.AsyncCallback;

@CustomLog
class LongHierarchicalLedgerManager extends AbstractHierarchicalLedgerManager {
    public LongHierarchicalLedgerManager(MetadataStore store, ScheduledExecutorService scheduler,
                                         String ledgerRootPath) {
        super(store, scheduler, ledgerRootPath);
    }

    public long getLedgerId(String pathName) throws IOException {
        if (!pathName.startsWith(ledgerRootPath)) {
            throw new IOException("it is not a valid hashed path name : " + pathName);
        }
        String hierarchicalPath = pathName.substring(ledgerRootPath.length() + 1);
        return StringUtils.stringToLongHierarchicalLedgerId(hierarchicalPath);
    }

    public String getLedgerPath(long ledgerId) {
        return ledgerRootPath + StringUtils.getLongHierarchicalLedgerPath(ledgerId);
    }

    //
    // Active Ledger Manager
    //

    public void asyncProcessLedgers(final BookkeeperInternalCallbacks.Processor<Long> processor,
                                    final AsyncCallback.VoidCallback finalCb,
                                    final Object context, final int successRc, final int failureRc) {

        // If it succeeds, proceed with our own recursive ledger processing for the 63-bit id ledgers

View on GitHub (pinned to 820761864e)

Solutions

1. Pass only paths returned by getLedgerPath for this manager (with the exact ledgerRootPath prefix)
2. Verify the ledgerRootPath configuration matches the layout used to create the ledger paths
3. Confirm the correct ledger manager type is configured to match the existing layout in the metadata store

Example fix

// before
long id = lm.getLedgerId("/ledgers/0001/0234"); // throws if prefix != ledgerRootPath
// after
String path = lm.getLedgerPath(ledgerId);
if (path != null && path.startsWith(ledgerRootPath)) {
    long id = lm.getLedgerId(path);
}

if (path == null || !path.startsWith(ledgerRootPath + "/")) {
    throw new IllegalArgumentException("not a valid long-hierarchical ledger path: " + path);
}

static boolean isValidLedgerPath(String path, String ledgerRootPath) {
    return path != null && path.startsWith(ledgerRootPath)
        && path.length() > ledgerRootPath.length() + 1;
}

try {
    long id = lm.getLedgerId(path);
} catch (IOException e) {
    if (e.getMessage().startsWith("it is not a valid hashed path name")) {
        LOG.error("Path {} does not match ledgerRootPath={}", path, ledgerRootPath);
    }
    throw e;
}

When it happens

Trigger: Calling getLedgerId with a path produced by a different ledger manager layout, a path missing the ledger root prefix, or after the ledgerRootPath config changed between runs so stored/returned paths no longer match the prefix.

Common situations: Mixing HierarchicalLedgerManager and LongHierarchicalLedgerManager layouts; migrating ledger manager types without updating the layout; typo/mismatch in ledgerRootPath configuration; calling getLedgerId on the root path itself or a non-ledger node.

Related errors

• The path ${path} doesn't look like a valid path for a Bookie
• Couldn't find ledgerid in path
• Cursor %s mark-delete position %s is ahead of the last posit
• Timeout during managed ledger close
• Timeout during managed ledger delete operation

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