apache/pulsar · error · IllegalArgumentException

Property

Error message

Property 

What it means

JavaInstanceMain.main() reads the JVM system property pulsar.functions.instance.classpath (FUNCTIONS_INSTANCE_CLASSPATH) to build the classloader for the function instance. If the property is absent it throws IllegalArgumentException immediately, because without it the user function's classes cannot be located.

Source

Thrown at pulsar-functions/runtime-all/src/main/java/org/apache/pulsar/functions/instance/JavaInstanceMain.java:82

                    .getMethod("shutdown");
        } catch (ClassNotFoundException | NoSuchMethodException e) {
            // ignore
        }
        log4j2ShutdownMethod = shutdownMethod;
    }

    public JavaInstanceMain() {
    }

    public static void main(String[] args) throws Exception {

        // Set root classloader to current classpath
        ClassLoader root = Thread.currentThread().getContextClassLoader();

        // Get classpath for function instance
        String functionInstanceClasspath = System.getProperty(FUNCTIONS_INSTANCE_CLASSPATH);
        if (functionInstanceClasspath == null) {
            throw new IllegalArgumentException("Property " + FUNCTIONS_INSTANCE_CLASSPATH + " is not set!");
        }

        List<File> files = new LinkedList<>();
        for (String entry : functionInstanceClasspath.split(":")) {
            if (isBlank(entry)) {
                continue;
            }
            // replace any asterisks i.e. wildcards as they don't work with url classloader
            File f = new File(entry.replace("*", ""));
            if (f.exists()) {
                if (f.isDirectory()) {
                    files.addAll(Arrays.asList(f.listFiles()));
                } else {
                    files.add(new File(entry));
                }
            } else {
                System.out.println(
                        String.format("[WARN] %s on functions instance classpath does not exist", f.getAbsolutePath()));

View on GitHub (pinned to 820761864e)

Solutions

1. Launch with -Dpulsar.functions.instance.classpath set to the function instance jar(s), e.g. -Dpulsar.functions.instance.classpath=/pulsar/instances/java-instance.jar.
2. Use the standard pulsar function runner scripts rather than invoking JavaInstanceMain manually.
3. Verify the function worker distribution is complete and versions match the broker (the script that sets the property ships with it).
4. If using a custom runtime, set the property in the process environment before exec (the classpath is normally derived from it).

Example fix

// before
java org.apache.pulsar.functions.instance.JavaInstanceMain ...
// after
java -Dpulsar.functions.instance.classpath=/pulsar/instances/java-instance.jar org.apache.pulsar.functions.instance.JavaInstanceMain ...

if (System.getProperty("pulsar.functions.instance.classpath") == null) { throw new IllegalStateException("Start with -Dpulsar.functions.instance.classpath=<instance jars>"); }

null

try { JavaInstanceMain.main(args); } catch (IllegalArgumentException e) { if (e.getMessage().contains("Property")) { System.err.println("Missing -Dpulsar.functions.instance.classpath; use the provided function runner script"); } throw e; }

When it happens

Trigger: Launching the function instance via java org.apache.pulsar.functions.instance.JavaInstanceMain without -Dpulsar.functions.instance.classpath=... set, or a launcher script (e.g. the function runtime assembly scripts) that fails to pass it.

Common situations: Hand-rolled java commands instead of the provided function runner scripts; corrupted/older function worker distribution where the instance jar's startup script doesn't set the property; custom exec runtimes missing the flag.

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

• Invalid config [socks5Proxy.address]
• error while booting GSSAPI client
• (wraps ClassNotFoundException for BrokerEntryMetadataInterce
• (wraps ClassNotFoundException for interceptor)
• User class must be in class path

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