apache/pulsar · error · IllegalArgumentException

Package URL ${packagePath} is not valid

Error message

Package URL ${packagePath} is not valid

What it means

FunctionActioner.getPackageFile validates a function's package URL (file:// scheme) before converting it to a local file path. If PackageUrlValidator.isValidPackageUrl rejects the URL, an IllegalArgumentException is thrown and the function fails to start.

Source

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

                    .getFunctionMetaData().getFunctionDetails();
            log.error().attr("tenant", details.getTenant())
                    .attr("namespace", details.getNamespace())
                    .attr("functionName", details.getName())
                    .exception(ex).log("Error starting function");
            functionRuntimeInfo.setStartupException(ex);
        }
    }

    private String getPackageFile(FunctionMetaData functionMetaData, FunctionDetails functionDetails, int instanceId,
                                  PackageLocationMetaData pkgLocation,
                                  FunctionDetails.ComponentType componentType)
            throws URISyntaxException, IOException, ClassNotFoundException, PulsarAdminException {
        String packagePath = pkgLocation.getPackagePath();
        boolean isPkgUrlProvided = isFunctionPackageUrlSupported(packagePath);
        String packageFile;
        if (isPkgUrlProvided && packagePath.startsWith(FILE)) {
            if (!packageUrlValidator.isValidPackageUrl(componentType, packagePath)) {
                throw new IllegalArgumentException("Package URL " + packagePath + " is not valid");
            }
            URL url = new URL(packagePath);
            File pkgFile = new File(url.toURI());
            packageFile = pkgFile.getAbsolutePath();
        } else if (FunctionCommon.isFunctionCodeBuiltin(functionDetails, componentType)) {
            FunctionDetails functionDetailsCopy = new FunctionDetails();
            functionDetailsCopy.copyFrom(functionMetaData.getFunctionDetails());
            File pkgFile = getBuiltinArchive(componentType, functionDetailsCopy);
            packageFile = pkgFile.getAbsolutePath();
        } else {
            File pkgDir = new File(workerConfig.getDownloadDirectory(),
                    getDownloadPackagePath(functionMetaData, instanceId));
            pkgDir.mkdirs();
            File pkgFile = new File(
                    pkgDir,
                    new File(getDownloadFileName(functionMetaData.getFunctionDetails(),
                            pkgLocation)).getName());
            downloadFile(pkgFile, isPkgUrlProvided, functionMetaData, instanceId, pkgLocation, componentType);

View on GitHub (pinned to 820761864e)

Solutions

1. Fix the packagePath to a valid, well-formed file:// URL pointing to an existing function jar
2. Upload the package via Pulsar's package management service (or HTTP) instead of a raw file URL
3. Check worker configuration for allowed package URL rules and align the path with them

Example fix

// before
pkgLocation.setPackagePath("file:///opt/../funcs/my-func.jar"); // rejected
// after
pkgLocation.setPackagePath("file:///pulsar/functions/my-func.jar");

String path = pkgLocation.getPackagePath();
if (path != null && path.startsWith("file:")) {
    try {
        File f = new File(new URL(path).toURI());
        if (!f.isFile()) throw new IllegalArgumentException("package file missing: " + f);
    } catch (URISyntaxException | MalformedURLException e) {
        throw new IllegalArgumentException("bad package URL: " + path, e);
    }
}

boolean isValidFilePackageUrl(String path) {
    if (path == null || !path.startsWith("file:")) return false;
    try { return new File(new URL(path).toURI()).isFile(); }
    catch (Exception e) { return false; }
}

try {
    functionActioner.startFunction(...);
} catch (IllegalArgumentException e) {
    if (e.getMessage().startsWith("Package URL")) {
        // resubmit function with corrected packagePath
    } else { throw e; }
}

When it happens

Trigger: Starting a function whose PackageLocationMetadata.packagePath is a file:// URL that fails validation (disallowed scheme characters, path outside allowed roots, malformed URL).

Common situations: Hand-edited function configs with a bad file:// path; uploading functions referencing worker-inaccessible local paths; path traversal or non-jar artifacts rejected by the validator.

Related errors

• Package URL ${pkgLocationPath} is not valid
• 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
• Function Name not provided

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