apache/pulsar · error · MetadataStoreException

Invalid metadata URL. Must start with 'oxia://'.

Error message

Invalid metadata URL. Must start with 'oxia://'.

What it means

OxiaMetadataStoreProvider.getServiceAddressAndNamespace validates that the metadata URL starts with the provider's scheme ('oxia://'). A null URL or a URL with a different scheme throws MetadataStoreException('Invalid metadata URL. Must start with \'oxia://\'.'); a URL with more than one '/' after the host throws a similar 'Invalid metadata URL.' error for a malformed namespace segment.

Source

Thrown at pulsar-metadata/src/main/java/org/apache/pulsar/metadata/impl/oxia/OxiaMetadataStoreProvider.java:62

            String metadataURL, MetadataStoreConfig metadataStoreConfig, boolean enableSessionWatcher)
            throws MetadataStoreException {
        var serviceAddress = getServiceAddressAndNamespace(metadataURL);
        try {
            return new OxiaMetadataStore(
                    serviceAddress.getLeft(),
                    serviceAddress.getRight(),
                    metadataStoreConfig,
                    enableSessionWatcher);
        } catch (Exception e) {
            throw new MetadataStoreException(e);
        }
    }

    @NonNull
    Pair<String, String> getServiceAddressAndNamespace(String metadataURL)
            throws MetadataStoreException {
        if (metadataURL == null || !metadataURL.startsWith(urlScheme() + "://")) {
            throw new MetadataStoreException("Invalid metadata URL. Must start with 'oxia://'.");
        }
        final var addressWithNamespace = metadataURL.substring("oxia://".length());
        final var split = addressWithNamespace.split("/");
        if (split.length > 2) {
            throw new MetadataStoreException(
                    "Invalid metadata URL."
                            + " the oxia metadata format should be 'oxia://host:port/[namespace]'.");
        }
        if (split.length == 1) {
            // Use default namespace
            return Pair.of(split[0], DefaultNamespace);
        }
        return Pair.of(split[0], split[1]);
    }

    public AsyncOxiaClient getOxiaClient(String metadataURL) throws MetadataStoreException {
        var pair = getServiceAddressAndNamespace(metadataURL);
        try {

View on GitHub (pinned to 820761864e)

Solutions

1. Set metadataUrl to a well-formed Oxia URL: oxia://<service-address>[/<namespace>].
2. Confirm the selected metadata provider matches the URL scheme (oxia provider for oxia://).
3. Ensure at most one '/' separating the service address from the namespace.
4. Validate the URL string before startup (see validationCode).

Example fix

// before
metadataUrl=http://oxia-coordinator:6648
// after
metadataUrl=oxia://oxia-coordinator:6648/default

static void validateOxiaUrl(String url) {
    if (url == null || !url.startsWith("oxia://"))
        throw new IllegalArgumentException("metadataUrl must start with oxia://");
    String rest = url.substring("oxia://".length());
    if (rest.isEmpty() || rest.split("/").length > 2)
        throw new IllegalArgumentException("metadataUrl must be oxia://<address>[/<namespace>]");
}

static boolean isOxiaUrl(String url) {
    return url != null && url.startsWith("oxia://")
        && url.substring("oxia://".length()).split("/").length <= 2;
}

try {
    MetadataStore s = MetadataStoreFactory.create(metadataUrl);
} catch (MetadataStoreException e) {
    if (e.getMessage().startsWith("Invalid metadata URL")) {
        log.error("Fix metadataUrl scheme/format for oxia provider: {}", metadataUrl);
    } else throw e;
}

When it happens

Trigger: Configuring metadataUrl with a wrong scheme (e.g. 'http://', 'rocksdb://', missing scheme) while the Oxia metadata store provider is selected, or passing an oxia URL with extra path segments like 'oxia://host/ns/extra'.

Common situations: Copy-pasting a URL from a non-Oxia setup; forgetting to switch metadataUrl when changing the metadata provider; typos like 'oxia:/' or 'oxia//'; embedding namespace incorrectly with double slashes.

Related errors

• Expected target metadata store to be Oxia
• Invalid metadata URL. the oxia metadata format should be 'ox
• Timeout during mark-delete operation
• Timeout during clear backlog operation
• Timeout during skip messages operation

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