{"record":{"id":"38674fcc0567f0a4","repo":"apache/pulsar","slug":"the-supplied-python-file-does-not-exist","errorCode":null,"errorMessage":"The supplied python file does not exist","messagePattern":"The supplied python file does not exist","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"pulsar-functions/utils/src/main/java/org/apache/pulsar/functions/utils/FunctionConfigUtils.java","lineNumber":899,"sourceCode":"                && functionConfig.getProcessingGuarantees() == FunctionConfig.ProcessingGuarantees.EFFECTIVELY_ONCE) {\n            throw new IllegalArgumentException(\n                    \"When effectively once processing guarantee is specified, retain Key ordering cannot be set\");\n        }\n        if (functionConfig.getRetainKeyOrdering() != null && functionConfig.getRetainKeyOrdering()\n                && functionConfig.getRetainOrdering() != null && functionConfig.getRetainOrdering()) {\n            throw new IllegalArgumentException(\"Only one of retain ordering or retain key ordering can be set\");\n        }\n\n        if (!isEmpty(functionConfig.getPy()) && !org.apache.pulsar.common.functions.Utils\n                .isFunctionPackageUrlSupported(functionConfig.getPy())\n                && functionConfig.getPy().startsWith(BUILTIN)) {\n            String filename = functionConfig.getPy();\n            if (filename.contains(\"..\")) {\n                throw new IllegalArgumentException(\"Invalid filename: \" + filename);\n            }\n\n            if (!new File(filename).exists()) {\n                throw new IllegalArgumentException(\"The supplied python file does not exist\");\n            }\n        }\n        if (!isEmpty(functionConfig.getGo()) && !org.apache.pulsar.common.functions.Utils\n                .isFunctionPackageUrlSupported(functionConfig.getGo())\n                && functionConfig.getGo().startsWith(BUILTIN)) {\n            String filename = functionConfig.getGo();\n            if (filename.contains(\"..\")) {\n                throw new IllegalArgumentException(\"Invalid filename: \" + filename);\n            }\n\n            if (!new File(filename).exists()) {\n                throw new IllegalArgumentException(\"The supplied go file does not exist\");\n            }\n        }\n\n        if (functionConfig.getInputSpecs() != null) {\n            functionConfig.getInputSpecs().forEach((topicName, conf) -> {\n                // receiver queue size should be >= 0","sourceCodeStart":881,"sourceCodeEnd":917,"githubUrl":"https://github.com/apache/pulsar/blob/820761864ed8e2a7d2e52dd9763ad2ae117c1395/pulsar-functions/utils/src/main/java/org/apache/pulsar/functions/utils/FunctionConfigUtils.java#L881-L917","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Verify the exact built-in name with `pulsar-admin functions builtins list` and correct setPy() accordingly","Install/deploy the built-in functions archive (pulsar-functions/python-examples or the official distribution) on the workers","Use an externally hosted package URL (http(s):// or file://) instead of builtin:// if you control the artifact","Confirm you are validating/submitting against the same host/cluster where the built-in is installed"],"exampleFix":"// before\nconf.setPy(\"builtin://exclamation.py\");   // not installed\n// after\nconf.setPy(\"builtin://wordcount.py\");     // exists in the installed builtins","handlingStrategy":"validation","validationCode":"String py = conf.getPy();\nif (py != null && py.startsWith(\"builtin://\")) {\n    String name = py.substring(\"builtin://\".length());\n    java.io.File f = new java.io.File(\n        \"/pulsar/functions/\" + name); // adjust to the worker functions directory\n    if (!f.exists()) {\n        throw new IllegalStateException(\"Built-in python function not found: \" + name);\n    }\n}","typeGuard":"boolean builtinExists(String s) {\n    return s != null && s.startsWith(\"builtin://\")\n        && new java.io.File(s.substring(\"builtin://\".length())).exists();\n}","tryCatchPattern":"try {\n    admin.functions().createFunction(conf);\n} catch (IllegalArgumentException e) {\n    if (e.getMessage().equals(\"The supplied python file does not exist\")) {\n        // deploy builtins or fall back to a hosted package URL\n        conf.setPy(\"https://example.com/functions/myfunc.py\");\n        admin.functions().createFunction(conf);\n    } else throw e;\n}","preventionTips":["Run `pulsar-admin functions builtins list` and keep names in a checked-in manifest","Ensure the built-in functions archive is installed on every broker/worker","Prefer explicit http(s)/file package URLs when you need reproducible artifacts across clusters"],"tags":["pulsar-functions","config-validation","filesystem","builtin"],"backgroundTag":"builtin-function-not-found","analyzedSha":"820761864ed8e2a7d2e52dd9763ad2ae117c1395","analyzedAt":"2026-09-06T00:14:20.138Z","contentChangedAt":"2026-09-06T00:14:20.138Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}