apache/pulsar · critical · RuntimeException

Failed to load the worker service

Error message

Failed to load the worker service ${metadata}

What it means

This is the public entry point WorkerServiceLoader.load(metadata, narExtractionDirectory) that delegates to the internal load and rethrows any IOException as a RuntimeException('Failed to load the worker service ' + metadata). It indicates the worker service could not be loaded from the NAR described by the WorkerServiceMetadata (archive path, definition), with the underlying IOException as cause.

Solutions

1. Inspect the cause IOException in the stack trace to identify the actual file/IO failure.
2. Confirm metadata.getArchivePath() exists and is a valid NAR archive readable by the process.
3. Fix the functions_worker.yml NAR package configuration and restart the functions worker.
4. Verify narExtractionDirectory permissions and disk space.

Example fix

// before
// functions_worker.yml: functionsWorkerServiceNarPackage: /opt/pulsar/workersvc.nar (file missing)
// after
// ensure file exists and path is correct:
// ls -l /opt/pulsar/workersvc.nar && chmod a+r /opt/pulsar/workersvc.nar
// then restart the functions worker

WorkerServiceMetadata md = /* built metadata */;
File archive = md.getArchivePath().toFile();
if (archive == null || !archive.isFile() || !archive.canRead()) {
    throw new IllegalStateException("Worker service archive missing: " + md);
}

try {
    WorkerServiceWithClassLoader svc = WorkerServiceLoader.load(config, narExtractionDirectory);
} catch (RuntimeException e) {
    log.error("Failed to load worker service: {}", e.getCause(), e);
    throw e; // fail fast at startup
}

When it happens

Trigger: Calling WorkerServiceLoader.load(WorkerConfig, ...) / load(metadata, narExtractionDirectory) when the internal load throws IOException: NAR missing, unreadable, corrupt, or extraction to narExtractionDirectory fails.

Common situations: Broker startup with a misconfigured worker service NAR; NAR deleted between metadata creation and load; read/extract permission issues; wrong narExtractionDirectory.

Related errors

• Failed to get the worker service definition from
• Access to environment variable
• Another drain is in progress
• AutoAck cannot be altered
• Batch Configs cannot be found

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

Appendix: source

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

        } catch (IOException ioe) {
            log.error().attr("narPackage", wsNarPackage).exception(ioe)
                    .log("Failed to get the worker service definition");
            throw new RuntimeException("Failed to get the worker service definition from "
                + wsNarPackage, ioe);
        }

        WorkerServiceMetadata metadata = new WorkerServiceMetadata();
        Path narPath = Paths.get(wsNarPackage);
        metadata.setArchivePath(narPath);
        metadata.setDefinition(definition);

        WorkerServiceWithClassLoader service;
        try {
            service = load(metadata, narExtractionDirectory);
        } catch (IOException e) {
            log.error().attr("metadata", metadata).exception(e)
                    .log("Failed to load the worker service");
            throw new RuntimeException("Failed to load the worker service " + metadata, e);
        }

        log.info().attr("metadata", metadata)
                .log("Successfully loaded worker service");
        return service;
    }
}

View on GitHub (pinned to 820761864e)