apache/pulsar · error · MetadataStoreException

Invalid metadata URL. the oxia metadata format should be 'ox

Error message

Invalid metadata URL. the oxia metadata format should be 'oxia://host:port/[namespace]'.

What it means

MetadataStoreException thrown by OxiaMetadataStoreProvider.getServiceAddressAndNamespace when the oxia metadata URL contains more than one '/' after the scheme, i.e. more path segments than a single optional namespace. The provider validates the URL shape before creating the store.

Source

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

                    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 {
            return OxiaClientBuilder.create(pair.getLeft())
                    .namespace(pair.getRight())
                    .asyncClient().get();
        } catch (Exception e) {
            throw new MetadataStoreException(e);

View on GitHub (pinned to 820761864e)

Solutions

1. Use the format 'oxia://host:port' or 'oxia://host:port/[namespace]' with at most one path segment.
2. Remove extra path segments, query strings, or duplicate slashes from the metadata URL.
3. Verify the broker's metadataUrl configuration value; ensure it starts with oxia:// and has no stray '/' beyond the namespace.
4. If migrating from ZooKeeper, do not reuse the zk:// URL path structure; oxia only accepts host:port and an optional namespace.

Example fix

// before
metadataUrl=oxia://oxia1:6648/oxia/namespace1
// after
metadataUrl=oxia://oxia1:6648/namespace1

String url = metadataUrl;
boolean valid = url != null && url.startsWith("oxia://")
    && url.substring("oxia://".length()).split("/").length <= 2;
if (!valid) throw new IllegalArgumentException("metadataUrl must be oxia://host:port[/namespace]");

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

try (MetadataStore store = MetadataStore.create(metadataUrl, ...)) {
    // use store
} catch (MetadataStoreException e) {
    log.error("Bad oxia metadata URL: {}", metadataUrl, e);
    throw new ConfigurationException(e);
}

When it happens

Trigger: Calling MetadataStore.create with a metadata URL like 'oxia://host:port/a/b' (split into more than 2 parts), e.g. a full URL with a trailing path such as 'oxia://host:port/ns/extra'.

Common situations: Copy-pasting a ZooKeeper-style metadata URL into the oxia:// scheme, appending stray trailing slashes plus a namespace ('oxia://host:port//ns'), or templated configs that leave placeholder path segments in the URL.

Related errors

• Expected target metadata store to be Oxia
• Metadata store address argument is required (--metadata-stor
• is not an instance of MetadataStore
• Neither METADATA_STORE_INSTANCE configuration set in the BK
• Unsupported MetadataStoreConfig query parameter '${key}'. Su

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