{"record":{"id":"c95efeca66084f22","repo":"apache/pulsar","slug":"invalid-metadata-url-must-start-with-oxia","errorCode":null,"errorMessage":"Invalid metadata URL. Must start with 'oxia://'.","messagePattern":"Invalid metadata URL\\. Must start with 'oxia://'\\.","errorType":"exception","errorClass":"MetadataStoreException","httpStatus":null,"severity":"error","filePath":"pulsar-metadata/src/main/java/org/apache/pulsar/metadata/impl/oxia/OxiaMetadataStoreProvider.java","lineNumber":62,"sourceCode":"            String metadataURL, MetadataStoreConfig metadataStoreConfig, boolean enableSessionWatcher)\n            throws MetadataStoreException {\n        var serviceAddress = getServiceAddressAndNamespace(metadataURL);\n        try {\n            return new OxiaMetadataStore(\n                    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 {","sourceCodeStart":44,"sourceCodeEnd":80,"githubUrl":"https://github.com/apache/pulsar/blob/820761864ed8e2a7d2e52dd9763ad2ae117c1395/pulsar-metadata/src/main/java/org/apache/pulsar/metadata/impl/oxia/OxiaMetadataStoreProvider.java#L44-L80","documentation":"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.","triggerScenarios":"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'.","commonSituations":"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.","solutions":["Set metadataUrl to a well-formed Oxia URL: oxia://<service-address>[/<namespace>].","Confirm the selected metadata provider matches the URL scheme (oxia provider for oxia://).","Ensure at most one '/' separating the service address from the namespace.","Validate the URL string before startup (see validationCode)."],"exampleFix":"// before\nmetadataUrl=http://oxia-coordinator:6648\n// after\nmetadataUrl=oxia://oxia-coordinator:6648/default","handlingStrategy":"validation","validationCode":"static void validateOxiaUrl(String url) {\n    if (url == null || !url.startsWith(\"oxia://\"))\n        throw new IllegalArgumentException(\"metadataUrl must start with oxia://\");\n    String rest = url.substring(\"oxia://\".length());\n    if (rest.isEmpty() || rest.split(\"/\").length > 2)\n        throw new IllegalArgumentException(\"metadataUrl must be oxia://<address>[/<namespace>]\");\n}","typeGuard":"static boolean isOxiaUrl(String url) {\n    return url != null && url.startsWith(\"oxia://\")\n        && url.substring(\"oxia://\".length()).split(\"/\").length <= 2;\n}","tryCatchPattern":"try {\n    MetadataStore s = MetadataStoreFactory.create(metadataUrl);\n} catch (MetadataStoreException e) {\n    if (e.getMessage().startsWith(\"Invalid metadata URL\")) {\n        log.error(\"Fix metadataUrl scheme/format for oxia provider: {}\", metadataUrl);\n    } else throw e;\n}","preventionTips":["Keep metadataUrl scheme in sync with the configured metadata provider","Validate config at startup with a URL pattern check","Copy known-good example URLs rather than editing schemes by hand"],"tags":["configuration","url-validation","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-14T00:17:10.932Z"}