apache/pulsar · error · IllegalArgumentException

Per instance RAM requested, %s, for function is greater than

Error message

Per instance RAM requested, %s, for function is greater than the maximum required, %s

What it means

validateMaxResourcesRequired enforces a worker-configured maximum RAM per function instance. If functionDetails.resources.ram exceeds functionInstanceMaxResources.ram, Pulsar throws IllegalArgumentException with both values.

Source

Thrown at pulsar-functions/runtime/src/main/java/org/apache/pulsar/functions/runtime/kubernetes/KubernetesRuntimeFactory.java:488

                }
            }
        }
    }

    void validateMaxResourcesRequired(FunctionDetails functionDetails) {
        if (functionInstanceMaxResources != null) {
            Double maxCpu = functionInstanceMaxResources.getCpu();
            Long maxRam = functionInstanceMaxResources.getRam();

            if (maxCpu != null && functionDetails.getResources().getCpu() > maxCpu) {
                throw new IllegalArgumentException(
                        String.format(
                                "Per instance CPU requested, %s, for function is greater than the maximum required, %s",
                                functionDetails.getResources().getCpu(), maxCpu));
            }

            if (maxRam != null && functionDetails.getResources().getRam() > maxRam) {
                throw new IllegalArgumentException(
                        String.format(
                                "Per instance RAM requested, %s, for function is greater than the maximum required, %s",
                                functionDetails.getResources().getRam(), maxRam));
            }
        }
    }

    void validateResourcesGranularityAndProportion(FunctionDetails functionDetails) {
        final long baseMillis = 1000;
        long multiples = 0L;
        if (functionInstanceResourceGranularities != null) {
            Double grnCpu = functionInstanceResourceGranularities.getCpu();
            Long grnRam = functionInstanceResourceGranularities.getRam();
            if (grnCpu != null) {
                // convert cpus to milli-cores to avoid loss of precision
                long grnCpuMillis = Math.round(baseMillis * grnCpu);
                if (grnCpuMillis > 0) {
                    long cpuMillis = Math.round(baseMillis * functionDetails.getResources().getCpu());

View on GitHub (pinned to 820761864e)

Solutions

Reduce the function's --ram to at most the configured maximum.
Scale out with more instances at lower per-instance RAM instead of one large instance.
Ask the cluster admin to raise functionInstanceMaxResources.ram if needed.
Verify byte conversion of the --ram value (e.g. 1Gi = 1073741824).

Example fix

// before
--ram 17179869184  (16Gi)
// after
--ram 8589934592  (8Gi, assuming max ram is 8Gi)

Defensive patterns

Strategy: validation

Validate before calling

Long maxRam = workerCfg.getFunctionInstanceMaxResources().getRam();
if (maxRam != null && details.getResources().getRam() > maxRam) {
    throw new IllegalArgumentException("ram " + details.getResources().getRam() + " > allowed max " + maxRam);
}

Try / catch

try { admin.functions().updateFunction(config); } catch (IllegalArgumentException e) { if (e.getMessage().contains("greater than the maximum")) { /* lower ram / scale out instances */ } throw e; }

Prevention

Cap RAM in deployment templates to the cluster maximum
Double-check byte conversions (Gi = 1073741824) when setting --ram
Re-validate stored function configs against new max-resources settings after admin changes

When it happens

Trigger: Submitting/updating a function whose --ram (bytes) is greater than the cluster's configured functionInstanceMaxResources.ram (doAdmissionChecks -> validateMaxResourcesRequired, line 488).

Common situations: Generously sizing memory 'to be safe'; unit confusion between MB/GB and bytes when passing --ram; configs copied from clusters without maximums; max lowered by admins after initial deployment.

Related errors

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