apache/pulsar · error · RuntimeException

No JavaInstanceJar specified

Error message

No JavaInstanceJar specified

What it means

ProcessRuntimeFactory.initialize() resolves the Java instance jar location. If javaInstanceJarFile was not set on the factory (no function worker config value) it falls back to the system property pulsar.functions.java.instance.file; when neither is present it throws RuntimeException('No JavaInstanceJar specified'). The factory cannot spawn Java function processes without the instance jar.

Source

Thrown at pulsar-functions/runtime/src/main/java/org/apache/pulsar/functions/runtime/process/ProcessRuntimeFactory.java:151

        this.authConfig = authConfig;
        this.secretsProviderConfigurator = secretsProviderConfigurator;
        this.javaInstanceJarFile = javaInstanceJarFile;
        this.pythonInstanceFile = pythonInstanceFile;
        this.extraDependenciesDir = extraDependenciesDir;
        this.narExtractionDirectory = narExtractionDirectory;
        this.logDirectory = logDirectory;
        this.authenticationEnabled = authenticationEnabled;

        // if things are not specified, try to figure out by env properties
        if (this.javaInstanceJarFile == null) {
            String envJavaInstanceJarLocation = System.getProperty(FunctionCacheEntry.JAVA_INSTANCE_JAR_PROPERTY);
            if (null != envJavaInstanceJarLocation) {
                log.info().attr("location", envJavaInstanceJarLocation)
                        .log("Java instance jar location is not defined,"
                                + " using the location defined in system environment");
                this.javaInstanceJarFile = envJavaInstanceJarLocation;
            } else {
                throw new RuntimeException("No JavaInstanceJar specified");
            }
        }

        if (this.pythonInstanceFile == null) {
            String envPythonInstanceLocation = System.getProperty("pulsar.functions.python.instance.file");
            if (null != envPythonInstanceLocation) {
                log.info().attr("location", envPythonInstanceLocation)
                        .log("Python instance file location is not defined,"
                                + " using the location defined in system environment");
                this.pythonInstanceFile = envPythonInstanceLocation;
            } else {
                throw new RuntimeException("No PythonInstanceFile specified");
            }
        }

        if (this.logDirectory == null) {
            String envProcessContainerLogDirectory = System.getProperty("pulsar.functions.process.container.log.dir");
            if (null != envProcessContainerLogDirectory) {

View on GitHub (pinned to 820761864e)

Solutions

  1. Set the javaInstanceJar location in the function worker config (e.g. javaInstanceJarLocation) to the pulsar-functions/java-instance jar path.
  2. Or pass -Dpulsar.functions.java.instance.file=/path/to/java-instance.jar to the worker JVM.
  3. Use the standard Pulsar distribution/start scripts that set this property automatically.
  4. Double-check the config key spelling and that the worker config actually loaded (look for the 'Java instance jar location' log line).

Example fix

# before: worker.conf with no instance jar
# after
functionsWorkerCustomConfigs:
  javaInstanceJarLocation: /pulsar/instances/java-instance.jar
# or JVM arg: -Dpulsar.functions.java.instance.file=/pulsar/instances/java-instance.jar
Defensive patterns

Strategy: validation

Validate before calling

String jar = System.getProperty("pulsar.functions.java.instance.file");
if (jar == null || jar.isBlank()) {
    throw new IllegalStateException("Set pulsar.functions.java.instance.file (or javaInstanceJarLocation in worker config) before starting ProcessRuntimeFactory");
}
if (!Files.isRegularFile(Paths.get(jar))) {
    throw new IllegalStateException("java instance jar not found: " + jar);
}

Try / catch

try {
    factory.initialize(conf);
} catch (RuntimeException e) {
    if ("No JavaInstanceJar specified".equals(e.getMessage())) {
        // add -Dpulsar.functions.java.instance.file=/pulsar/instances/java-instance.jar and restart
    }
    throw e;
}

Prevention

When it happens

Trigger: Starting the function worker with runtime = PROCESS without configuring the Java instance jar via the worker config, and without the pulsar.functions.java.instance.file system property; also when the configured path variable is null after config loading.

Common situations: Incomplete function worker.yml when switching from THREAD to PROCESS runtime; launching worker with a stripped-down config; upgrading and dropping a custom property; running the worker outside its standard distribution where the property was previously set in the startup script.

Related errors

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