{"record":{"id":"6bc7de1de682cc2f","repo":"apache/pulsar","slug":"no-javainstancejar-specified","errorCode":null,"errorMessage":"No JavaInstanceJar specified","messagePattern":"No JavaInstanceJar specified","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"pulsar-functions/runtime/src/main/java/org/apache/pulsar/functions/runtime/process/ProcessRuntimeFactory.java","lineNumber":151,"sourceCode":"        this.authConfig = authConfig;\n        this.secretsProviderConfigurator = secretsProviderConfigurator;\n        this.javaInstanceJarFile = javaInstanceJarFile;\n        this.pythonInstanceFile = pythonInstanceFile;\n        this.extraDependenciesDir = extraDependenciesDir;\n        this.narExtractionDirectory = narExtractionDirectory;\n        this.logDirectory = logDirectory;\n        this.authenticationEnabled = authenticationEnabled;\n\n        // if things are not specified, try to figure out by env properties\n        if (this.javaInstanceJarFile == null) {\n            String envJavaInstanceJarLocation = System.getProperty(FunctionCacheEntry.JAVA_INSTANCE_JAR_PROPERTY);\n            if (null != envJavaInstanceJarLocation) {\n                log.info().attr(\"location\", envJavaInstanceJarLocation)\n                        .log(\"Java instance jar location is not defined,\"\n                                + \" using the location defined in system environment\");\n                this.javaInstanceJarFile = envJavaInstanceJarLocation;\n            } else {\n                throw new RuntimeException(\"No JavaInstanceJar specified\");\n            }\n        }\n\n        if (this.pythonInstanceFile == null) {\n            String envPythonInstanceLocation = System.getProperty(\"pulsar.functions.python.instance.file\");\n            if (null != envPythonInstanceLocation) {\n                log.info().attr(\"location\", envPythonInstanceLocation)\n                        .log(\"Python instance file location is not defined,\"\n                                + \" using the location defined in system environment\");\n                this.pythonInstanceFile = envPythonInstanceLocation;\n            } else {\n                throw new RuntimeException(\"No PythonInstanceFile specified\");\n            }\n        }\n\n        if (this.logDirectory == null) {\n            String envProcessContainerLogDirectory = System.getProperty(\"pulsar.functions.process.container.log.dir\");\n            if (null != envProcessContainerLogDirectory) {","sourceCodeStart":133,"sourceCodeEnd":169,"githubUrl":"https://github.com/apache/pulsar/blob/820761864ed8e2a7d2e52dd9763ad2ae117c1395/pulsar-functions/runtime/src/main/java/org/apache/pulsar/functions/runtime/process/ProcessRuntimeFactory.java#L133-L169","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Set the javaInstanceJar location in the function worker config (e.g. javaInstanceJarLocation) to the pulsar-functions/java-instance jar path.","Or pass -Dpulsar.functions.java.instance.file=/path/to/java-instance.jar to the worker JVM.","Use the standard Pulsar distribution/start scripts that set this property automatically.","Double-check the config key spelling and that the worker config actually loaded (look for the 'Java instance jar location' log line)."],"exampleFix":"# before: worker.conf with no instance jar\n# after\nfunctionsWorkerCustomConfigs:\n  javaInstanceJarLocation: /pulsar/instances/java-instance.jar\n# or JVM arg: -Dpulsar.functions.java.instance.file=/pulsar/instances/java-instance.jar","handlingStrategy":"validation","validationCode":"String jar = System.getProperty(\"pulsar.functions.java.instance.file\");\nif (jar == null || jar.isBlank()) {\n    throw new IllegalStateException(\"Set pulsar.functions.java.instance.file (or javaInstanceJarLocation in worker config) before starting ProcessRuntimeFactory\");\n}\nif (!Files.isRegularFile(Paths.get(jar))) {\n    throw new IllegalStateException(\"java instance jar not found: \" + jar);\n}","typeGuard":null,"tryCatchPattern":"try {\n    factory.initialize(conf);\n} catch (RuntimeException e) {\n    if (\"No JavaInstanceJar specified\".equals(e.getMessage())) {\n        // add -Dpulsar.functions.java.instance.file=/pulsar/instances/java-instance.jar and restart\n    }\n    throw e;\n}","preventionTips":["Use the standard Pulsar distribution/start scripts that set the instance-file properties automatically.","Verify worker config keys (javaInstanceJarLocation) when migrating between THREAD and PROCESS runtime.","Include java-instance.jar in custom Docker images.","Fail fast in deployment checks if the property is absent."],"tags":["pulsar-functions","configuration","missing-env-var"],"backgroundTag":"missing-instance-jar-location","analyzedSha":"820761864ed8e2a7d2e52dd9763ad2ae117c1395","analyzedAt":"2026-09-06T00:14:20.138Z","contentChangedAt":"2026-09-06T00:14:20.138Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}