apache/pulsar · critical · IOException

Functions Worker Service Nar Package `${name}` does NOT prov

Error message

Functions Worker Service Nar Package `${name}` does NOT provide a functions worker service implementation

What it means

WorkerServiceLoader.load() extracts a functions worker NAR (nar package) and reads its WorkerServiceDefinition metadata. If the definition's handlerClass is blank, the NAR does not actually provide a functions worker service implementation, so loading fails with this IOException. This prevents Pulsar from starting a worker backed by an unusable package.

Source

Thrown at pulsar-functions/worker/src/main/java/org/apache/pulsar/functions/worker/service/WorkerServiceLoader.java:85

    /**
     * Load the worker service according to the worker service definition.
     *
     * @param metadata the worker service definition.
     * @return
     */
    static WorkerServiceWithClassLoader load(WorkerServiceMetadata metadata,
                                             String narExtractionDirectory) throws IOException {
        final File narFile = metadata.getArchivePath().toAbsolutePath().normalize().toFile();
        NarClassLoader ncl = NarClassLoaderBuilder.builder()
                .narFile(narFile)
                .parentClassLoader(WorkerService.class.getClassLoader())
                .extractionDirectory(narExtractionDirectory)
                .build();

        WorkerServiceDefinition phDef = getWorkerServiceDefinition(ncl);
        if (StringUtils.isBlank(phDef.getHandlerClass())) {
            throw new IOException("Functions Worker Service Nar Package `" + phDef.getName()
                + "` does NOT provide a functions worker service implementation");
        }

        try {
            Class<?> handlerClass = ncl.loadClass(phDef.getHandlerClass());
            Object handler = handlerClass.getDeclaredConstructor().newInstance();
            if (!(handler instanceof WorkerService)) {
                throw new IOException("Class " + phDef.getHandlerClass()
                    + " does not implement worker service interface");
            }
            WorkerService ph = (WorkerService) handler;
            return new WorkerServiceWithClassLoader(ph, ncl);
        } catch (Throwable t) {
            rethrowIOException(t);
            return null;
        }
    }

View on GitHub (pinned to 820761864e)

Solutions

1. Set functionsWorkerServiceNarPackage to the correct worker service NAR (e.g. pulsar-functions/worker-something artifact), not a connector NAR
2. Rebuild the NAR ensuring META-INF/services contains the WorkerServiceDefinition with a non-blank handlerClass
3. Verify NAR integrity/version compatibility with the running Pulsar version

Example fix

// before
functionsWorkerServiceNarPackage=/pulsar/connectors/pulsar-io-kafka-2.10.0.nar
// after: use a real worker service NAR
functionsWorkerServiceNarPackage=/pulsar/instances/pulsar-functions-worker-all-2.10.0.nar

// before starting the worker, check the NAR is a worker service package
java.util.zip.ZipFile nar = new java.util.zip.ZipFile(narPath);
boolean hasDef = nar.stream().anyMatch(e ->
    e.getName().equals("META-INF/services/org.apache.pulsar.functions.worker.service.WorkerServiceDefinition"));
if (!hasDef) throw new IllegalStateException("Not a functions worker service NAR: " + narPath);

When it happens

Trigger: Pointing functionsWorkerServiceNarPackage at a NAR that is not a functions worker service NAR (e.g. an offset/truncate/other connector NAR, an empty or corrupted archive, or a NAR whose META-INF/services definition lacks handlerClass).

Common situations: Configuration mistakes swapping connector and worker NARs; building the NAR without the WorkerServiceDefinition resource; using a NAR from an incompatible Pulsar version.

Related errors

• config file is nil.
• Class ${handlerClass} does not implement worker service inte
• No offloader found for driver '${driverName}'. Please make s
• Could not open configuration file
• Malformed configuration file

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