{"record":{"id":"0fcfa269a8cf219b","repo":"apache/pulsar","slug":"no-pythoninstancefile-specified","errorCode":null,"errorMessage":"No PythonInstanceFile specified","messagePattern":"No PythonInstanceFile 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":163,"sourceCode":"            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) {\n                this.logDirectory = envProcessContainerLogDirectory;\n            } else {\n                // use a default location\n                this.logDirectory = Paths.get(\"logs\").toFile().getAbsolutePath();\n            }\n        }\n        this.logDirectory = this.logDirectory + \"/functions\";\n\n        if (this.extraDependenciesDir == null) {\n            String envProcessContainerExtraDependenciesDir =\n                    System.getProperty(\"pulsar.functions.extra.dependencies.dir\");\n            if (null != envProcessContainerExtraDependenciesDir) {","sourceCodeStart":145,"sourceCodeEnd":181,"githubUrl":"https://github.com/apache/pulsar/blob/820761864ed8e2a7d2e52dd9763ad2ae117c1395/pulsar-functions/runtime/src/main/java/org/apache/pulsar/functions/runtime/process/ProcessRuntimeFactory.java#L145-L181","documentation":"ProcessRuntimeFactory.initialize() resolves the Python instance file similarly: if pythonInstanceFile is not set on the factory it falls back to the system property pulsar.functions.python.instance.file; if neither exists it throws RuntimeException('No PythonInstanceFile specified'). Without the python instance source file, PROCESS-runtime Python functions cannot be launched.","triggerScenarios":"Initializing ProcessRuntimeFactory when a Python function will run (or eagerly during initialize) and neither the configured pythonInstanceFile nor the pulsar.functions.python.instance.file system property is present.","commonSituations":"Worker config missing pythonInstanceFile because only Java functions were expected; deploying Python functions after the fact without restarting the worker with the property; custom Docker images that omit /pulsar/instances/python-instance.zip; mismatches after upgrading the Pulsar distribution.","solutions":["Set pythonInstanceFile in the function worker config to the python instance file path (e.g. /pulsar/instances/python-instance.zip).","Or pass -Dpulsar.functions.python.instance.file=/pulsar/instances/python-instance.zip to the worker JVM.","Ensure the Pulsar distribution image actually ships the python instance file at the configured path.","Restart the worker after adding the config; initialize() runs once at startup."],"exampleFix":"# before\n# (no python instance configured)\n# after\n-Dpulsar.functions.python.instance.file=/pulsar/instances/python-instance.zip\n# or worker config: pythonInstanceFile: /pulsar/instances/python-instance.zip","handlingStrategy":"validation","validationCode":"String py = System.getProperty(\"pulsar.functions.python.instance.file\");\nif (py == null || py.isBlank() || !Files.exists(Paths.get(py))) {\n    throw new IllegalStateException(\"Set pulsar.functions.python.instance.file to a valid python instance file before running Python functions\");\n}","typeGuard":null,"tryCatchPattern":"try {\n    factory.initialize(conf);\n} catch (RuntimeException e) {\n    if (\"No PythonInstanceFile specified\".equals(e.getMessage())) {\n        // add -Dpulsar.functions.python.instance.file=/pulsar/instances/python-instance.zip and restart\n    }\n    throw e;\n}","preventionTips":["Set pythonInstanceFile in worker config if any Python functions may be deployed.","Confirm custom images ship /pulsar/instances/python-instance.zip.","Keep client/worker versions aligned so instance files match expectations.","Check for the 'Python instance file location' log line at startup to confirm configuration loaded."],"tags":["pulsar-functions","configuration","missing-env-var","python"],"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"}