What causes "Function parallelism must be a positive number" in apache/pulsar?

Set parallelism to a positive integer (typically 1 for single-instance, N for scaled-out)

apache/pulsar · error · IllegalArgumentException

Function parallelism must be a positive number

Error message

Function parallelism must be a positive number

What it means

FunctionConfig parallelism controls how many instances of the function run. doCommonChecks rejects configs where parallelism is explicitly set to zero or a negative number, since the runtime cannot launch a non-positive number of instances.

Source

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

            }
        }

        if (!isEmpty(functionConfig.getLogTopic())) {
            if (!TopicName.isValid(functionConfig.getLogTopic())) {
                throw new IllegalArgumentException(
                        String.format("LogTopic topic %s is invalid", functionConfig.getLogTopic()));
            }
        }

        if (!isEmpty(functionConfig.getDeadLetterTopic())) {
            if (!TopicName.isValid(functionConfig.getDeadLetterTopic())) {
                throw new IllegalArgumentException(
                        String.format("DeadLetter topic %s is invalid", functionConfig.getDeadLetterTopic()));
            }
        }

        if (functionConfig.getParallelism() != null && functionConfig.getParallelism() <= 0) {
            throw new IllegalArgumentException("Function parallelism must be a positive number");
        }
        // Ensure that topics aren't being used as both input and output
        verifyNoTopicClash(allInputTopics, functionConfig.getOutput());

        WindowConfig windowConfig = functionConfig.getWindowConfig();
        if (windowConfig != null) {
            // set auto ack to false since windowing framework is responsible
            // for acking and not the function framework
            @SuppressWarnings("deprecation")
            Boolean windowAutoAck = functionConfig.getAutoAck();
            if (windowAutoAck != null && windowAutoAck) {
                throw new IllegalArgumentException("Cannot enable auto ack when using windowing functionality");
            }
            WindowConfigUtils.validate(windowConfig);
        }

        if (functionConfig.getResources() != null) {
            ResourceConfigUtils.validate(functionConfig.getResources());

View on GitHub (pinned to 820761864e)

Solutions

Set parallelism to a positive integer (typically 1 for single-instance, N for scaled-out)
Only set the field when you have a computed positive value; leave it null to use the default
Guard programmatic generation: Math.max(1, computedParallelism)
Fix autoscaling logic that can emit 0

Example fix

// before
config.setParallelism(replicas); // replicas could be 0
// after
config.setParallelism(Math.max(1, replicas));

Defensive patterns

Strategy: validation

Validate before calling

Integer p = config.getParallelism();
if (p != null && p <= 0) {
    throw new IllegalArgumentException("parallelism must be positive, got " + p);
}

Type guard

boolean positiveParallelism(FunctionConfig c) {
    return c.getParallelism() == null || c.getParallelism() > 0;
}

Try / catch

try {
    admin.functions().createFunction(functionConfig, sourceConfigLocation);
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("parallelism must be a positive number")) {
        config.setParallelism(1); // or a computed positive value, then retry once
    } else { throw e; }
}

Prevention

Use Math.max(1, computed) when generating parallelism programmatically
Leave parallelism null to inherit defaults instead of setting 0
Validate integer fields that come from autoscaling computations
Add manifest linting that rejects parallelism <= 0

When it happens

Trigger: createFunction/updateFunction with functionConfig.getParallelism() != null && parallelism <= 0: e.g. parallelism: 0 in YAML, a computed value defaulting to 0, or CLI --parallelism 0.

Common situations: Programmatic config generation where parallelism comes from an unset integer variable (int default 0), autoscaling scripts computing 0 replicas, copy-pasted manifests with parallelism commented incorrectly.

Related errors

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