{"record":{"id":"77edcb0d472ff8ec","repo":"apache/pulsar","slug":"invalid-metadata-url-the-oxia-metadata-format-sho","errorCode":null,"errorMessage":"Invalid metadata URL. the oxia metadata format should be 'oxia://host:port/[namespace]'.","messagePattern":"Invalid metadata URL\\. the oxia metadata format should be 'oxia://host:port/\\[namespace\\]'\\.","errorType":"exception","errorClass":"MetadataStoreException","httpStatus":null,"severity":"error","filePath":"pulsar-metadata/src/main/java/org/apache/pulsar/metadata/impl/oxia/OxiaMetadataStoreProvider.java","lineNumber":67,"sourceCode":"                    serviceAddress.getLeft(),\n                    serviceAddress.getRight(),\n                    metadataStoreConfig,\n                    enableSessionWatcher);\n        } catch (Exception e) {\n            throw new MetadataStoreException(e);\n        }\n    }\n\n    @NonNull\n    Pair<String, String> getServiceAddressAndNamespace(String metadataURL)\n            throws MetadataStoreException {\n        if (metadataURL == null || !metadataURL.startsWith(urlScheme() + \"://\")) {\n            throw new MetadataStoreException(\"Invalid metadata URL. Must start with 'oxia://'.\");\n        }\n        final var addressWithNamespace = metadataURL.substring(\"oxia://\".length());\n        final var split = addressWithNamespace.split(\"/\");\n        if (split.length > 2) {\n            throw new MetadataStoreException(\n                    \"Invalid metadata URL.\"\n                            + \" the oxia metadata format should be 'oxia://host:port/[namespace]'.\");\n        }\n        if (split.length == 1) {\n            // Use default namespace\n            return Pair.of(split[0], DefaultNamespace);\n        }\n        return Pair.of(split[0], split[1]);\n    }\n\n    public AsyncOxiaClient getOxiaClient(String metadataURL) throws MetadataStoreException {\n        var pair = getServiceAddressAndNamespace(metadataURL);\n        try {\n            return OxiaClientBuilder.create(pair.getLeft())\n                    .namespace(pair.getRight())\n                    .asyncClient().get();\n        } catch (Exception e) {\n            throw new MetadataStoreException(e);","sourceCodeStart":49,"sourceCodeEnd":85,"githubUrl":"https://github.com/apache/pulsar/blob/820761864ed8e2a7d2e52dd9763ad2ae117c1395/pulsar-metadata/src/main/java/org/apache/pulsar/metadata/impl/oxia/OxiaMetadataStoreProvider.java#L49-L85","documentation":"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.","triggerScenarios":"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'.","commonSituations":"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.","solutions":["Use the format 'oxia://host:port' or 'oxia://host:port/[namespace]' with at most one path segment.","Remove extra path segments, query strings, or duplicate slashes from the metadata URL.","Verify the broker's metadataUrl configuration value; ensure it starts with oxia:// and has no stray '/' beyond the namespace.","If migrating from ZooKeeper, do not reuse the zk:// URL path structure; oxia only accepts host:port and an optional namespace."],"exampleFix":"// before\nmetadataUrl=oxia://oxia1:6648/oxia/namespace1\n// after\nmetadataUrl=oxia://oxia1:6648/namespace1","handlingStrategy":"validation","validationCode":"String url = metadataUrl;\nboolean valid = url != null && url.startsWith(\"oxia://\")\n    && url.substring(\"oxia://\".length()).split(\"/\").length <= 2;\nif (!valid) throw new IllegalArgumentException(\"metadataUrl must be oxia://host:port[/namespace]\");","typeGuard":"static boolean isValidOxiaUrl(String url) {\n    return url != null && url.startsWith(\"oxia://\")\n        && url.substring(7).split(\"/\").length <= 2;\n}","tryCatchPattern":"try (MetadataStore store = MetadataStore.create(metadataUrl, ...)) {\n    // use store\n} catch (MetadataStoreException e) {\n    log.error(\"Bad oxia metadata URL: {}\", metadataUrl, e);\n    throw new ConfigurationException(e);\n}","preventionTips":["Keep metadata URLs to scheme://host:port plus at most one namespace path segment.","Validate config values at startup before brokers/clients connect.","Do not reuse ZooKeeper URL paths for oxia:// URLs.","Add config linting in CI for metadataUrl patterns."],"tags":["configuration","metadata-store","url-format","oxia"],"backgroundTag":"invalid-metadata-url","analyzedSha":"820761864ed8e2a7d2e52dd9763ad2ae117c1395","analyzedAt":"2026-09-06T00:14:20.138Z","contentChangedAt":"2026-09-06T00:14:20.138Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}