What causes "Invalid package url: %s" in apache/pulsar?

Use a package URL permitted by the worker's package URL validator (check its configuration)

apache/pulsar · error · IllegalArgumentException

Invalid package url: %s

Error message

Invalid package url: %s

What it means

When the function package path is an HTTP URL, the worker validates it with getPackageUrlValidator() before streaming. If the URL is not acceptable (wrong host scheme/extension/policy), an IllegalArgumentException('Invalid package url: ...') is thrown while writing the streaming response.

Source

Thrown at pulsar-functions/worker/src/main/java/org/apache/pulsar/functions/worker/rest/api/ComponentImpl.java:1458

                ? functionMetaData.getTransformFunctionPackageLocation().getPackagePath()
                : functionMetaData.getPackageLocation().getPackagePath();

        FunctionDetails.ComponentType componentType = transformFunction
                ? FunctionDetails.ComponentType.FUNCTION
                : InstanceUtils.calculateSubjectType(functionMetaData.getFunctionDetails());

        return getStreamingOutput(pkgPath, componentType);
    }

    private StreamingOutput getStreamingOutput(String pkgPath) {
        return getStreamingOutput(pkgPath, null);
    }

    private StreamingOutput getStreamingOutput(String pkgPath, FunctionDetails.ComponentType componentType) {
        return output -> {
            if (pkgPath.startsWith(Utils.HTTP)) {
                if (!worker().getPackageUrlValidator().isValidPackageUrl(componentType, pkgPath)) {
                    throw new IllegalArgumentException("Invalid package url: " + pkgPath);
                }
                URL url = URI.create(pkgPath).toURL();
                try (InputStream inputStream = url.openStream()) {
                    IOUtils.copy(inputStream, output);
                }
            } else if (pkgPath.startsWith(Utils.FILE)) {
                if (!worker().getPackageUrlValidator().isValidPackageUrl(componentType, pkgPath)) {
                    throw new IllegalArgumentException("Invalid package url: " + pkgPath);
                }
                URI url = URI.create(pkgPath);
                File file = new File(url.getPath());
                Files.copy(file.toPath(), output);
            } else if (pkgPath.startsWith(Utils.BUILTIN)
                    && !worker().getWorkerConfig().getUploadBuiltinSinksSources()) {
                Path narPath = getBuiltinArchivePath(pkgPath, componentType);
                log.info().attr("pkgPath", pkgPath).attr("narPath", narPath).log("Loading from");
                try (InputStream in = new FileInputStream(narPath.toString())) {
                    IOUtils.copy(in, output, 1024);

View on GitHub (pinned to 820761864e)

Solutions

Use a package URL permitted by the worker's package URL validator (check its configuration)
Prefer file:// (dlog) package URLs uploaded via BookKeeper
Validate the URL format client-side before submitting the function
Check worker logs for the validator's rejection reason

Example fix

// before
String pkg = "http://evil.example.com/x.jar";
// after
String pkg = "file:///pulsar/functions/myfunc.jar"; // or an allow-listed http URL

Defensive patterns

Strategy: validation

Validate before calling

boolean ok = pkgPath.startsWith("http") && pkgPath.matches("^https?://[a-zA-Z0-9.-]+/[-a-zA-Z0-9@:%._+~#=/]*\\.(jar|nar)$");
if (!ok) throw new IllegalArgumentException("URL not allowed by worker policy: " + pkgPath);

Try / catch

try { download(); } catch (IllegalArgumentException e) { log.error("package URL rejected: {}", e.getMessage()); }

Prevention

Use dlog/file package URLs uploaded through BookKeeper
Keep package URLs on the worker's allow-list (host/extension)
Percent-encode URLs properly
Validate URLs at function-submission time, not download time

When it happens

Trigger: Downloading a function whose package URL starts with http(s) and fails PackageUrlValidator.isValidPackageUrl; also URI.create(pkgPath).toURL() may throw for malformed URLs.

Common situations: Function submitted with an http package URL the worker policy disallows; unvalidated/malicious URL blocked by the validator; URL with characters that break URI parsing.

Related errors

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