apache/pulsar · error · IllegalArgumentException

Package URL ${pkgLocationPath} is not valid

Error message

Package URL ${pkgLocationPath} is not valid

What it means

FunctionActioner.downloadFile downloads the function package from an HTTP URL and validates the URL first. If PackageUrlValidator.isValidPackageUrl rejects the http(s) URL, an IllegalArgumentException is thrown before any download happens.

Source

Thrown at pulsar-functions/worker/src/main/java/org/apache/pulsar/functions/worker/FunctionActioner.java:273

        do {
            tempPkgFile = new File(
                    pkgDir,
                    pkgFile.getName() + "." + instanceId + "." + UUID.randomUUID());
        } while (tempPkgFile.exists() || !tempPkgFile.createNewFile());
        String pkgLocationPath = pkgLocation.getPackagePath();
        boolean downloadFromHttp = isPkgUrlProvided && pkgLocationPath.startsWith(HTTP);
        boolean downloadFromPackageManagementService = isPkgUrlProvided && hasPackageTypePrefix(pkgLocationPath);
        log.info().attr("tenant", details.getTenant())
                .attr("namespace", details.getNamespace())
                .attr("functionName", details.getName())
                .attr("pkgFile", tempPkgFile)
                .attr("source", downloadFromHttp ? pkgLocationPath : pkgLocation)
                .log("Function package file will be downloaded");

        long downloadStartMs = System.currentTimeMillis();
        if (downloadFromHttp) {
            if (!packageUrlValidator.isValidPackageUrl(componentType, pkgLocationPath)) {
                throw new IllegalArgumentException("Package URL " + pkgLocationPath + " is not valid");
            }
            FunctionCommon.downloadFromHttpUrl(pkgLocationPath, tempPkgFile);
        } else if (downloadFromPackageManagementService) {
            getPulsarAdmin().packages().download(pkgLocationPath, tempPkgFile.getPath());
        } else {
            try (FileOutputStream tempPkgFos = new FileOutputStream(tempPkgFile)) {
                WorkerUtils.downloadFromBookkeeper(
                        dlogNamespace,
                        tempPkgFos,
                        pkgLocationPath);
            }
        }
        log.info().attr("tenant", details.getTenant())
                .attr("namespace", details.getNamespace())
                .attr("functionName", details.getName())
                .attr("pkgFile", tempPkgFile)
                .attr("sizeBytes", tempPkgFile.length())
                .attr("durationMs", System.currentTimeMillis() - downloadStartMs)

View on GitHub (pinned to 820761864e)

Solutions

1. Correct the package URL in the function metadata to a valid http(s) URL
2. Use Pulsar package management service URLs (as an alternative branch, no HTTP validation needed)
3. Review worker's package URL validator configuration for what is accepted

Example fix

// before
pkgLocation.setPackagePath("http:/bad-host/func.jar"); // throws
// after
pkgLocation.setPackagePath("https://broker.example.com/functions/my-func.jar");

String url = pkgLocation.getPackagePath();
if (url != null && (url.startsWith("http:") || url.startsWith("https:"))) {
    try {
        new java.net.URL(url).openConnection().connect(); // reachable check
    } catch (IOException e) {
        throw new IllegalArgumentException("package URL unreachable/invalid: " + url, e);
    }
}

boolean isValidHttpPackageUrl(String url) {
    try {
        java.net.URL u = new java.net.URL(url);
        return (u.getProtocol().equals("http") || u.getProtocol().equals("https")) && u.getHost() != null;
    } catch (Exception e) { return false; }
}

try {
    functionActioner.startFunction(...);
} catch (IllegalArgumentException e) {
    if (e.getMessage().startsWith("Package URL")) {
        // re-upload package and fix metadata URL
    } else { throw e; }
}

When it happens

Trigger: Downloading a function package whose packagePath is an http(s) URL that fails validation (malformed URL, disallowed host/scheme, path traversal).

Common situations: Typos in the package URL; pointing at an untrusted or non-whitelisted host; URL-encoding issues in the package path stored in function metadata.

Related errors

• Package URL ${packagePath} is not valid
• --destination-file needs to be specified
• Unsupported url protocol
• 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

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