apache/pulsar · error · RuntimeException

No PythonInstanceFile specified

Error message

No PythonInstanceFile specified

What it means

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.

Source

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

            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) {
                this.logDirectory = envProcessContainerLogDirectory;
            } else {
                // use a default location
                this.logDirectory = Paths.get("logs").toFile().getAbsolutePath();
            }
        }
        this.logDirectory = this.logDirectory + "/functions";

        if (this.extraDependenciesDir == null) {
            String envProcessContainerExtraDependenciesDir =
                    System.getProperty("pulsar.functions.extra.dependencies.dir");
            if (null != envProcessContainerExtraDependenciesDir) {

View on GitHub (pinned to 820761864e)

Solutions

1. Set pythonInstanceFile in the function worker config to the python instance file path (e.g. /pulsar/instances/python-instance.zip).
2. Or pass -Dpulsar.functions.python.instance.file=/pulsar/instances/python-instance.zip to the worker JVM.
3. Ensure the Pulsar distribution image actually ships the python instance file at the configured path.
4. Restart the worker after adding the config; initialize() runs once at startup.

Example fix

# before
# (no python instance configured)
# after
-Dpulsar.functions.python.instance.file=/pulsar/instances/python-instance.zip
# or worker config: pythonInstanceFile: /pulsar/instances/python-instance.zip

String py = System.getProperty("pulsar.functions.python.instance.file");
if (py == null || py.isBlank() || !Files.exists(Paths.get(py))) {
    throw new IllegalStateException("Set pulsar.functions.python.instance.file to a valid python instance file before running Python functions");
}

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

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Invalid schema class %s
• No JavaInstanceJar specified
• Unknown component type: %s
• Access to environment variable %s is not allowed.
• PulsarAdmin is not enabled in function worker

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