apache/pulsar · error · IllegalStateException

Function Package management service is disabled. Please enab

Error message

Function Package management service is disabled. Please enable it to use ${functionPkgUrl}

What it means

Thrown as IllegalStateException when a function/sink/source package URL uses a package-management-service scheme (package://, via Utils.hasPackageTypePrefix) but the worker has functionsWorkerEnablePackageManagement disabled. The worker cannot resolve package:// URLs without its internal package management service, so it rejects the request up front.

Source

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

            componentPackageFile = FunctionCommon.createPkgTempFile();
            componentPackageFile.deleteOnExit();
            if (worker().getWorkerConfig().isFunctionsWorkerEnablePackageManagement()) {
                worker().getBrokerAdmin().packages().download(
                        existingPackagePath,
                        componentPackageFile.getAbsolutePath());
            } else {
                WorkerUtils.downloadFromBookkeeper(worker().getDlogNamespace(),
                        componentPackageFile, existingPackagePath);
            }
        }
        return componentPackageFile;
    }

    protected File getPackageFile(FunctionDetails.ComponentType componentType, String functionPkgUrl)
            throws IOException, PulsarAdminException {
        if (Utils.hasPackageTypePrefix(functionPkgUrl)) {
            if (!worker().getWorkerConfig().isFunctionsWorkerEnablePackageManagement()) {
                throw new IllegalStateException("Function Package management service is disabled. "
                        + "Please enable it to use " + functionPkgUrl);
            }
            return downloadPackageFile(worker(), functionPkgUrl);
        } else {
            if (!worker().getPackageUrlValidator().isValidPackageUrl(componentType, functionPkgUrl)) {
                throw new IllegalArgumentException("Function Package url is not valid."
                        + "supported url (http/https/file)");
            }
            try {
                return FunctionCommon.extractFileFromPkgURL(functionPkgUrl);
            } catch (Exception e) {
                throw new IllegalArgumentException(String.format("Encountered error \"%s\" "
                                + "when getting %s package from %s", e.getMessage(),
                        ComponentTypeUtils.toString(componentType), functionPkgUrl), e);
            }
        }
    }

View on GitHub (pinned to 820761864e)

Solutions

Set functionsWorkerEnablePackageManagement=true in the functions worker configuration (workerConfig) and restart the functions worker.
Use an http(s):// or file:// package URL instead if you do not want to enable package management.
Upload the package via the REST upload endpoint only after enabling the service.

Example fix

// before (conf/functions_worker.yml)
functionsWorkerEnablePackageManagement: false
// after (conf/functions_worker.yml)
functionsWorkerEnablePackageManagement: true

Defensive patterns

Strategy: validation

Validate before calling

boolean usesPackageManagement(String url) { return url != null && url.startsWith("package://"); }
if (usesPackageManagement(functionPkgUrl)
        && !workerConfig.isFunctionsWorkerEnablePackageManagement()) {
    throw new IllegalStateException(
        "package:// URL supplied but functionsWorkerEnablePackageManagement is false");
}

Try / catch

try {
    admin.functions().registerFunction(tenant, namespace, name, config);
} catch (PulsarAdminException e) {
    if (e.getMessage() != null && e.getMessage().contains("management service is disabled")) {
        // fall back to http/file URL or enable package management and retry
    }
    throw e;
}

Prevention

Confirm functionsWorkerEnablePackageManagement=true in the worker config before using package:// URLs.
Check cluster/version support for package management before adopting it in tooling.
Keep a non-package-management URL format as a documented fallback.

When it happens

Trigger: Passing a package:// URL (functionPkgUrl or existingPackagePath) to any Function/Sink/Source register/update API while the target worker's WorkerConfig has functionsWorkerEnablePackageManagement=false (the default).

Common situations: Using the Pulsar functions package management feature introduced in newer versions against a worker/cluster where it was never enabled; mixed-version clusters where the client supports package:// but the worker config does not; copying example code that assumes package management is on.

Related errors

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