apache/pulsar · error · IllegalArgumentException

Unsupported url protocol

Error message

Unsupported url protocol 

What it means

FunctionCommon.extractFileFromPkgURL only supports file://, http:// and https:// package URLs. Any other scheme (e.g. ftp://, s3://, function:// without support, or a malformed URL with no recognizable protocol) falls through to this IllegalArgumentException listing the supported protocols.

Source

Thrown at pulsar-functions/utils/src/main/java/org/apache/pulsar/functions/utils/FunctionCommon.java:268

    public static File createPkgTempFile() throws IOException {
        return File.createTempFile("functions", ".tmp");
    }

    public static File extractFileFromPkgURL(String destPkgUrl) throws IOException, URISyntaxException {
        if (destPkgUrl.startsWith(Utils.FILE)) {
            URL url = new URL(destPkgUrl);
            File file = new File(url.toURI());
            if (!file.exists()) {
                throw new IOException(destPkgUrl + " does not exists locally");
            }
            return file;
        } else if (destPkgUrl.startsWith("http")) {
            File tempFile = createPkgTempFile();
            tempFile.deleteOnExit();
            downloadFromHttpUrl(destPkgUrl, tempFile);
            return tempFile;
        } else {
            throw new IllegalArgumentException("Unsupported url protocol "
                    + destPkgUrl + ", supported url protocols: [file/http/https]");
        }
    }

    public static String getFullyQualifiedInstanceId(Instance instance) {
        return getFullyQualifiedInstanceId(
                instance.getFunctionMetaData().getFunctionDetails().getTenant(),
                instance.getFunctionMetaData().getFunctionDetails().getNamespace(),
                instance.getFunctionMetaData().getFunctionDetails().getName(),
                instance.getInstanceId());
    }

    public static String getFullyQualifiedInstanceId(String tenant, String namespace,
                                                     String functionName, int instanceId) {
        return String.format("%s/%s/%s:%d", tenant, namespace, functionName, instanceId);
    }

    public static final long getSequenceId(MessageId messageId) {

View on GitHub (pinned to 820761864e)

Solutions

1. Prefix local paths with file:// and use http:// or https:// URLs for remote artifacts
2. Upload the artifact to an HTTP(S)-reachable repository and reference that URL
3. If using Pulsar package management, ensure the Pulsar version supports the function:// scheme in this code path, or download the package and pass a file:// URL
4. Check for typos/trailing whitespace in the configured pkgUrl

Example fix

// before
new CreateFunction().setPkgUrl("/opt/functions/app.jar") // no scheme -> throws
// after
new CreateFunction().setPkgUrl("file:///opt/functions/app.jar");

// Pre-validate the package URL scheme
String pkgUrl = "file:///opt/functions/app.jar";
if (!(pkgUrl.startsWith("file") || pkgUrl.startsWith("http"))) {
  throw new IllegalStateException("Unsupported pkgUrl scheme, use file:// or http(s)://: " + pkgUrl);
}

try {
  File f = FunctionCommon.extractFileFromPkgURL(pkgUrl);
} catch (IllegalArgumentException e) {
  if (e.getMessage() != null && e.getMessage().startsWith("Unsupported url protocol")) {
    log.error("Fix pkgUrl scheme: {}", e.getMessage());
    pkgUrl = "file://" + pkgUrl; // e.g. missing scheme on local path
  } else {
    throw e;
  }
}

When it happens

Trigger: Calling extractFileFromPkgURL with a destPkgUrl whose string neither starts with 'file' nor 'http' — e.g. using an ftp:// or s3:// URL, a bare path without a scheme like /path/to/app.jar, or a function://package-management URL passed to a code path that expects a downloadable URL.

Common situations: Pointing a function package at an object-store URI (s3://, gs://) the worker cannot download; forgetting the file:// prefix on a local path; scripting tools emitting relative paths; package management service URLs used where raw download URLs are required (older Pulsar versions).

Related errors

• Package URL ${packagePath} is not valid
• Package URL ${pkgLocationPath} is not valid
• Either a Java jar or a Python file or a Go executable binary
• Either a Java jar or a Python file or a Go executable binary
• Function Name not provided

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