apache/pulsar · error · IllegalArgumentException

The supplied python file does not exist

Error message

The supplied python file does not exist

What it means

For a built-in Python function (py starts with 'builtin://' and is not a supported package URL), the validator checks that a file with the given name actually exists on the local filesystem (new File(filename).exists()). Because built-ins resolve against the broker/worker's functions directory, a missing name throws IllegalArgumentException. Note the check runs in the process performing validation, so it tests that machine's filesystem.

Source

Thrown at pulsar-functions/utils/src/main/java/org/apache/pulsar/functions/utils/FunctionConfigUtils.java:899

                && functionConfig.getProcessingGuarantees() == FunctionConfig.ProcessingGuarantees.EFFECTIVELY_ONCE) {
            throw new IllegalArgumentException(
                    "When effectively once processing guarantee is specified, retain Key ordering cannot be set");
        }
        if (functionConfig.getRetainKeyOrdering() != null && functionConfig.getRetainKeyOrdering()
                && functionConfig.getRetainOrdering() != null && functionConfig.getRetainOrdering()) {
            throw new IllegalArgumentException("Only one of retain ordering or retain key ordering can be set");
        }

        if (!isEmpty(functionConfig.getPy()) && !org.apache.pulsar.common.functions.Utils
                .isFunctionPackageUrlSupported(functionConfig.getPy())
                && functionConfig.getPy().startsWith(BUILTIN)) {
            String filename = functionConfig.getPy();
            if (filename.contains("..")) {
                throw new IllegalArgumentException("Invalid filename: " + filename);
            }

            if (!new File(filename).exists()) {
                throw new IllegalArgumentException("The supplied python file does not exist");
            }
        }
        if (!isEmpty(functionConfig.getGo()) && !org.apache.pulsar.common.functions.Utils
                .isFunctionPackageUrlSupported(functionConfig.getGo())
                && functionConfig.getGo().startsWith(BUILTIN)) {
            String filename = functionConfig.getGo();
            if (filename.contains("..")) {
                throw new IllegalArgumentException("Invalid filename: " + filename);
            }

            if (!new File(filename).exists()) {
                throw new IllegalArgumentException("The supplied go file does not exist");
            }
        }

        if (functionConfig.getInputSpecs() != null) {
            functionConfig.getInputSpecs().forEach((topicName, conf) -> {
                // receiver queue size should be >= 0

View on GitHub (pinned to 820761864e)

Solutions

  1. Verify the exact built-in name with `pulsar-admin functions builtins list` and correct setPy() accordingly
  2. Install/deploy the built-in functions archive (pulsar-functions/python-examples or the official distribution) on the workers
  3. Use an externally hosted package URL (http(s):// or file://) instead of builtin:// if you control the artifact
  4. Confirm you are validating/submitting against the same host/cluster where the built-in is installed

Example fix

// before
conf.setPy("builtin://exclamation.py");   // not installed
// after
conf.setPy("builtin://wordcount.py");     // exists in the installed builtins
Defensive patterns

Strategy: validation

Validate before calling

String py = conf.getPy();
if (py != null && py.startsWith("builtin://")) {
    String name = py.substring("builtin://".length());
    java.io.File f = new java.io.File(
        "/pulsar/functions/" + name); // adjust to the worker functions directory
    if (!f.exists()) {
        throw new IllegalStateException("Built-in python function not found: " + name);
    }
}

Type guard

boolean builtinExists(String s) {
    return s != null && s.startsWith("builtin://")
        && new java.io.File(s.substring("builtin://".length())).exists();
}

Try / catch

try {
    admin.functions().createFunction(conf);
} catch (IllegalArgumentException e) {
    if (e.getMessage().equals("The supplied python file does not exist")) {
        // deploy builtins or fall back to a hosted package URL
        conf.setPy("https://example.com/functions/myfunc.py");
        admin.functions().createFunction(conf);
    } else throw e;
}

Prevention

When it happens

Trigger: Calling createFunction/updateFunction with setPy("builtin://typo-name.py") where no such .py file exists in the pulsar functions directory of the validating host; the built-in was never installed on the broker/worker.

Common situations: Typos in the built-in function name; built-in functions archive not deployed/extracted on the broker workers; a built-in available on one cluster but not another; validating on a laptop where the functions directory differs from the cluster.

Related errors

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