{"record":{"id":"19e7d921096dd57f","repo":"apache/pulsar","slug":"this-version-of-pulsar-client-supports-only-file","errorCode":null,"errorMessage":"This version of pulsar-client supports only file:// encryption keys; got '${fileUri}'.","messagePattern":"This version of pulsar-client supports only file:// encryption keys; got '(.+?)'\\.","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"pulsar-client-tools/src/main/java/org/apache/pulsar/client/cli/AbstractCmd.java","lineNumber":47,"sourceCode":"        return run();\n    }\n\n    abstract int run() throws Exception;\n\n    /**\n     * Resolve a {@code file:} URI (as accepted by the encryption-key flags) to a {@link Path}.\n     * Supports both the hierarchical form ({@code file:///abs/path}, where {@link URI#getPath()}\n     * is set) and the opaque relative form ({@code file:rel/path}, where the path lives in the\n     * scheme-specific part).\n     *\n     * @param fileUri a {@code file:} URI string\n     * @return the resolved {@link Path}\n     * @throws IllegalArgumentException if the URI scheme is not {@code file}\n     */\n    static Path fileUriToPath(String fileUri) {\n        URI uri = URI.create(fileUri);\n        if (!\"file\".equalsIgnoreCase(uri.getScheme())) {\n            throw new IllegalArgumentException(\"This version of pulsar-client supports only file:// \"\n                    + \"encryption keys; got '\" + fileUri + \"'.\");\n        }\n        String path = uri.getPath();\n        if (path == null) {\n            // Opaque (relative) file: URI, e.g. file:../certs/key.pem\n            path = uri.getSchemeSpecificPart();\n        }\n        return Path.of(path);\n    }\n}\n","sourceCodeStart":29,"sourceCodeEnd":58,"githubUrl":"https://github.com/apache/pulsar/blob/820761864ed8e2a7d2e52dd9763ad2ae117c1395/pulsar-client-tools/src/main/java/org/apache/pulsar/client/cli/AbstractCmd.java#L29-L58","documentation":"fileUriToPath resolves the --decryption-key (or similar) argument, which must be a file:// URI, into a filesystem Path. This build of pulsar-client only supports reading encryption keys from local files, so any other URI scheme (http, s3, classpath, etc.) is rejected with IllegalArgumentException before any I/O is attempted.","triggerScenarios":"Passing a key location with a scheme other than file to AbstractCmd.fileUriToPath, e.g. -dk http://host/key.pem, s3://bucket/key.pem, or an opaque URI whose scheme is not 'file'.","commonSituations":"Pointing the CLI at a key hosted on an HTTP server or object store because that is where secrets live; copying a config from a newer/other client that supports remote keys; typo like files:// or file:/path written without the scheme.","solutions":["Copy the key to local disk and pass a proper file:// URI, e.g. file:///etc/pulsar/key.pem","Check the URI scheme spelling and format (file:///abs/path); note opaque relative URIs like file:../certs/key.pem are handled via getSchemeSpecificPart","If the key must come from remote storage, pre-download it in a wrapper script before invoking the CLI, or use a client version/build that supports that key provider"],"exampleFix":"// before\n--decryption-key http://secrets.example.com/key.pem\n// after\ncurl -o /tmp/key.pem http://secrets.example.com/key.pem\n--decryption-key file:///tmp/key.pem","handlingStrategy":"validation","validationCode":"URI uri = URI.create(keyUri);\nif (!\"file\".equalsIgnoreCase(uri.getScheme()))\n    throw new IllegalArgumentException(\"key must be a file:// URI: \" + keyUri);","typeGuard":"static boolean isFileUri(String s) {\n    try { return \"file\".equalsIgnoreCase(URI.create(s).getScheme()); }\n    catch (Exception e) { return false; }\n}","tryCatchPattern":"try {\n    Path p = fileUriToPath(keyUri);\n} catch (IllegalArgumentException e) {\n    LOG.error(\"Only file:// encryption keys are supported: {}\", e.getMessage());\n    keyPath = downloadToLocalTemp(keyUri); // fallback\n}","preventionTips":["Store keys on local disk (or mount them) and always reference them with file:///abs/path","Normalize scheme spelling in config generation (no 'files:', no scheme-less paths)","Pre-download remote keys (http/s3) to a temp file in a wrapper script before invoking the CLI","Add a config linter step that asserts every key URI has scheme 'file'"],"tags":["cli","uri","encryption","validation"],"backgroundTag":"unsupported-uri-scheme","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"}