{"record":{"id":"1030ae91e60d4af8","repo":"apache/pulsar","slug":"function-package-management-service-is-disabled-p","errorCode":null,"errorMessage":"Function Package management service is disabled. Please enable it to use ${functionPkgUrl}","messagePattern":"Function Package management service is disabled\\. Please enable it to use (.+?)","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"pulsar-functions/worker/src/main/java/org/apache/pulsar/functions/worker/rest/api/ComponentImpl.java","lineNumber":1963,"sourceCode":"            componentPackageFile = FunctionCommon.createPkgTempFile();\n            componentPackageFile.deleteOnExit();\n            if (worker().getWorkerConfig().isFunctionsWorkerEnablePackageManagement()) {\n                worker().getBrokerAdmin().packages().download(\n                        existingPackagePath,\n                        componentPackageFile.getAbsolutePath());\n            } else {\n                WorkerUtils.downloadFromBookkeeper(worker().getDlogNamespace(),\n                        componentPackageFile, existingPackagePath);\n            }\n        }\n        return componentPackageFile;\n    }\n\n    protected File getPackageFile(FunctionDetails.ComponentType componentType, String functionPkgUrl)\n            throws IOException, PulsarAdminException {\n        if (Utils.hasPackageTypePrefix(functionPkgUrl)) {\n            if (!worker().getWorkerConfig().isFunctionsWorkerEnablePackageManagement()) {\n                throw new IllegalStateException(\"Function Package management service is disabled. \"\n                        + \"Please enable it to use \" + functionPkgUrl);\n            }\n            return downloadPackageFile(worker(), functionPkgUrl);\n        } else {\n            if (!worker().getPackageUrlValidator().isValidPackageUrl(componentType, functionPkgUrl)) {\n                throw new IllegalArgumentException(\"Function Package url is not valid.\"\n                        + \"supported url (http/https/file)\");\n            }\n            try {\n                return FunctionCommon.extractFileFromPkgURL(functionPkgUrl);\n            } catch (Exception e) {\n                throw new IllegalArgumentException(String.format(\"Encountered error \\\"%s\\\" \"\n                                + \"when getting %s package from %s\", e.getMessage(),\n                        ComponentTypeUtils.toString(componentType), functionPkgUrl), e);\n            }\n        }\n    }\n","sourceCodeStart":1945,"sourceCodeEnd":1981,"githubUrl":"https://github.com/apache/pulsar/blob/820761864ed8e2a7d2e52dd9763ad2ae117c1395/pulsar-functions/worker/src/main/java/org/apache/pulsar/functions/worker/rest/api/ComponentImpl.java#L1945-L1981","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","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."],"exampleFix":"// before (conf/functions_worker.yml)\nfunctionsWorkerEnablePackageManagement: false\n// after (conf/functions_worker.yml)\nfunctionsWorkerEnablePackageManagement: true","handlingStrategy":"validation","validationCode":"boolean usesPackageManagement(String url) { return url != null && url.startsWith(\"package://\"); }\nif (usesPackageManagement(functionPkgUrl)\n        && !workerConfig.isFunctionsWorkerEnablePackageManagement()) {\n    throw new IllegalStateException(\n        \"package:// URL supplied but functionsWorkerEnablePackageManagement is false\");\n}","typeGuard":null,"tryCatchPattern":"try {\n    admin.functions().registerFunction(tenant, namespace, name, config);\n} catch (PulsarAdminException e) {\n    if (e.getMessage() != null && e.getMessage().contains(\"management service is disabled\")) {\n        // fall back to http/file URL or enable package management and retry\n    }\n    throw e;\n}","preventionTips":["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."],"tags":["configuration","package-management","pulsar-functions"],"backgroundTag":"feature-disabled","analyzedSha":"820761864ed8e2a7d2e52dd9763ad2ae117c1395","analyzedAt":"2026-09-06T00:14:20.138Z","contentChangedAt":"2026-09-06T00:14:20.138Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}