apache/pulsar · error · java.lang.UnsupportedOperationException

Package Management Service is not enabled in the broker.

Error message

Package Management Service is not enabled in the broker.

What it means

PulsarService.getPackagesManagement() returns the broker's package management service, which is only initialized when packages management is enabled in broker configuration. If the service was never initialized (packagesManagement == null), it throws UnsupportedOperationException. The broker does not ship a default implementation enabled out of the box, so the admin REST/Java API for packages cannot be used until it is configured.

Source

Thrown at pulsar-broker/src/main/java/org/apache/pulsar/broker/PulsarService.java:2246

            functionWorkerService.get().initInBroker(
                config,
                workerConfig,
                pulsarResources,
                getInternalConfigurationData()
            );

            // TODO figure out how to handle errors from function worker service
            functionWorkerService.get().start(
                authenticationService,
                authorizationService,
                ErrorNotifier.getShutdownServiceImpl(this));
            log.info("Function worker service started");
        }
    }

    public PackagesManagement getPackagesManagement() throws UnsupportedOperationException {
        if (packagesManagement == null) {
            throw new UnsupportedOperationException("Package Management Service is not enabled in the broker.");
        }
        return packagesManagement;
    }

    private void startPackagesManagementService() throws IOException {
        // TODO: using provider to initialize the packages management service.
        this.packagesManagement = new PackagesManagementImpl(
                config.isPackagesManagementJsonSerializationEnabled(),
                config.isPackagesManagementAllowLegacyJavaSerialization());
        PackagesStorageProvider storageProvider = PackagesStorageProvider
            .newProvider(config.getPackagesManagementStorageProvider());
        DefaultPackagesStorageConfiguration storageConfiguration = new DefaultPackagesStorageConfiguration();
        storageConfiguration.setProperty(config.getProperties());
        PackagesStorage storage = storageProvider.getStorage(storageConfiguration);
        storage.initialize();
        this.packagesManagement.initialize(storage);
    }

View on GitHub (pinned to 820761864e)

Solutions

1. Enable the package management service in broker.conf (set the packages management storage/service configuration, e.g. packagesManagementStorageProvider and related packages-management settings) and restart the broker.
2. If packages are not needed, stop using the packages APIs/functions package features and deploy functions via other supported mechanisms.
3. Upgrade to a broker version/config combination where package management initialization is supported via its provider.
4. Verify with a quick call that the service is enabled before invoking packages operations in tooling.

Example fix

// before (broker.conf)
# (packages management not configured)

// after (broker.conf)
packagesManagementStorageProvider=org.apache.pulsar.packages.management.storage.bookkeeper.impl.BookKeeperPackagesStorageProvider
packagesStorageNamespace=public/packages

if (!brokerConfig.isPackageManagementEnabled()) {
    throw new IllegalStateException("Enable package management in broker.conf before using packages APIs");
}

boolean isPackagesManagementSupported(PulsarService pulsar) {
    try { return pulsar.getPackagesManagement() != null; }
    catch (UnsupportedOperationException e) { return false; }
}

try {
    PackagesManagement pm = pulsar.getPackagesManagement();
    // use pm
} catch (UnsupportedOperationException e) {
    log.warn("Package management not enabled on this broker: {}", e.getMessage());
}

When it happens

Trigger: Calling any Packages API (e.g. REST endpoints under /admin/v3/packages, or getPackagesManagement() programmatically) on a broker where the package management service is not enabled/initialized; brokers built without the packages management provider configured.

Common situations: Deploying a standard broker without enabling packages management and then attempting to upload/download functions or packages via CLI (pulsar-admin packages) or admin client; using a broker version where the service is behind configuration and assuming it is on by default.

Related errors

• webServicePort/webServicePortTls or http/https bindAddresses
• The retention size must > the backlog quota limit size, but
• The retention time must > the backlog quota limit time, but
• brokerDeleteInactiveTopicsEnabled and brokerCloseInactiveTop
• brokerCloseInactiveTopicsEnabled only supports brokerDeleteI

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