apache/pulsar · error · IllegalArgumentException

Encountered error "%s" when getting %s package from %s

Error message

Encountered error "%s" when getting %s package from %s

What it means

IllegalArgumentException wrapping the failure of FunctionCommon.extractFileFromPkgURL when the worker tried to download/extract a component package from a validated http/https/file existingPackagePath. The URL scheme was accepted but fetching or unpacking the archive failed, and the original exception message is embedded via %s.

Source

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

        worker.getBrokerAdmin().packages().download(packageName, file.toString());
        return file;
    }

    protected File getPackageFile(FunctionDetails.ComponentType componentType, String functionPkgUrl,
                                  String existingPackagePath, InputStream uploadedInputStream)
            throws IOException, PulsarAdminException {
        File componentPackageFile = null;
        if (isNotBlank(functionPkgUrl)) {
            componentPackageFile = getPackageFile(componentType, functionPkgUrl);
        } else if (existingPackagePath.startsWith(Utils.FILE) || existingPackagePath.startsWith(Utils.HTTP)) {
            if (!worker().getPackageUrlValidator().isValidPackageUrl(componentType, existingPackagePath)) {
                throw new IllegalArgumentException("Function Package url is not valid."
                        + "supported url (http/https/file)");
            }
            try {
                componentPackageFile = FunctionCommon.extractFileFromPkgURL(existingPackagePath);
            } catch (Exception e) {
                throw new IllegalArgumentException(String.format("Encountered error \"%s\" "
                                + "when getting %s package from %s", e.getMessage(),
                        ComponentTypeUtils.toString(componentType), existingPackagePath));
            }
        } else if (Utils.hasPackageTypePrefix(existingPackagePath)) {
            componentPackageFile = getPackageFile(componentType, existingPackagePath);
        } else if (uploadedInputStream != null) {
            componentPackageFile = WorkerUtils.dumpToTmpFile(uploadedInputStream);
        } else if (!existingPackagePath.startsWith(Utils.BUILTIN)) {
            componentPackageFile = FunctionCommon.createPkgTempFile();
            componentPackageFile.deleteOnExit();
            if (worker().getWorkerConfig().isFunctionsWorkerEnablePackageManagement()) {
                worker().getBrokerAdmin().packages().download(
                        existingPackagePath,
                        componentPackageFile.getAbsolutePath());
            } else {
                WorkerUtils.downloadFromBookkeeper(worker().getDlogNamespace(),
                        componentPackageFile, existingPackagePath);
            }

View on GitHub (pinned to 820761864e)

Solutions

1. Verify the package URL is reachable from the WORKER (curl the http(s) URL, or ls the file:// path on worker hosts) — the worker, not your client, fetches it.
2. Check the embedded cause message (%s) for the concrete failure: connection refused, 404, permission denied, etc., and fix accordingly.
3. Rebuild/re-upload the package if the archive is corrupt.
4. Use package:// URLs with the functions package management service to avoid ad-hoc HTTP/file hosting.

Example fix

// before
String existingPackagePath = "http://internal-host/jars/exclamation.jar"; // host unreachable from worker
// after
String existingPackagePath = "http://reachable-artifact-host:8080/jars/exclamation.jar";
// (verify with: curl -I http://reachable-artifact-host:8080/jars/exclamation.jar from the worker host)

// pre-flight check of package reachability (run from worker host or CI)
Process p = new ProcessBuilder("curl", "-fsSI", packageUrl).start();
if (p.waitFor() != 0) {
    throw new IllegalStateException("Package URL not reachable from worker: " + packageUrl);
}
// for file:// URLs: Files.isReadable(Paths.get(URI.create(packageUrl)))

try {
    admin.functions().registerFunction(tenant, namespace, name, config);
} catch (PulsarAdminException e) {
    if (e.getMessage() != null && e.getMessage().startsWith("Encountered error")) {
        // treat as transient/hosting problem: verify URL reachability, retry after fixing
    }
    throw e;
}

When it happens

Trigger: Registering/updating a function, sink, or source with existingPackagePath starting with http(s):// or file:// where: the remote HTTP(S) server is unreachable or returns 404/500; the file:// path does not exist or is unreadable on the worker; the downloaded file is corrupt or not a valid archive.

Common situations: Package hosted on an internal HTTP server that is down or moved; file:// path valid on the client machine but absent on the broker/worker hosts; firewall blocking the worker's outbound HTTP call; jar corrupted during upload or partially copied.

Related errors

• Cannot obtain authorization metadata from ${metadataUrl}
• Log folder creation error
• does not exists locally
• Loading '' failed due to
• <IOException message>

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