What causes "Failed to load the worker service ${metadata}" in apache/pulsar?

Inspect the cause IOException in the stack trace to identify the actual file/IO failure.

apache/pulsar · critical · RuntimeException

Failed to load the worker service ${metadata}

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.

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)

Solutions

Inspect the cause IOException in the stack trace to identify the actual file/IO failure.
Confirm metadata.getArchivePath() exists and is a valid NAR archive readable by the process.
Fix the functions_worker.yml NAR package configuration and restart the functions worker.
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

Defensive patterns

Strategy: try-catch

Validate before calling

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 / catch

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
}

Prevention

Log and inspect the cause IOException, not just the wrapper
Keep NAR extraction directory on a writable volume with free space
Test worker NAR loading in CI before deploying

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

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