apache/pulsar · error · RuntimeException

Unrecognized processing guarantee:

Error message

Unrecognized processing guarantee: 

What it means

FunctionCommon.convertProcessingGuarantee(FunctionConfig.ProcessingGuarantees) maps the config-side delivery semantics enum (ATMOST_ONCE, ATMOST_ONCE / ATLEAST_ONCE, EFFECTIVELY_ONCE) to the internal ProcessingGuarantees enum by name. An unmatched name throws this RuntimeException with the guarantee name. It guards against config values the internal pipeline cannot express.

Source

Thrown at pulsar-functions/utils/src/main/java/org/apache/pulsar/functions/utils/FunctionCommon.java:189

    public static FunctionConfig.Runtime convertRuntime(Runtime runtime) {
        for (FunctionConfig.Runtime type : FunctionConfig.Runtime.values()) {
            if (type.name().equals(runtime.name())) {
                return type;
            }
        }
        throw new RuntimeException("Unrecognized runtime: " + runtime.name());
    }

    public static ProcessingGuarantees convertProcessingGuarantee(
            FunctionConfig.ProcessingGuarantees processingGuarantees) {
        for (ProcessingGuarantees type :
                ProcessingGuarantees
                .values()) {
            if (type.name().equals(processingGuarantees.name())) {
                return type;
            }
        }
        throw new RuntimeException("Unrecognized processing guarantee: " + processingGuarantees.name());
    }

    public static FunctionConfig.ProcessingGuarantees convertProcessingGuarantee(
            ProcessingGuarantees processingGuarantees) {
        for (FunctionConfig.ProcessingGuarantees type : FunctionConfig.ProcessingGuarantees.values()) {
            if (type.name().equals(processingGuarantees.name())) {
                return type;
            }
        }
        throw new RuntimeException("Unrecognized processing guarantee: " + processingGuarantees.name());
    }

    public static TypeDefinition getSourceType(String className, TypePool typePool) {
        return getSourceType(typePool.describe(className).resolve());
    }

    public static TypeDefinition getSourceType(TypeDefinition sourceClass) {
        if (sourceClass.asErasure().isAssignableTo(Source.class)) {

View on GitHub (pinned to 820761864e)

Solutions

1. Upgrade broker/functions-worker to a version whose ProcessingGuarantees enum includes the config's value
2. Use supported guarantees: ATMOST_ONCE, ATLEAST_ONCE, or EFFECTIVELY_ONCE
3. Regenerate the config with a client version matching the server

Example fix

// before
"processingGuarantees": "PIPELINED" // unrecognized
// after
"processingGuarantees": "EFFECTIVELY_ONCE"

Set<String> internal = Arrays.stream(ProcessingGuarantees.values())
    .map(Enum::name).collect(Collectors.toSet());
if (!internal.contains(guarantees.name()))
    throw new IllegalArgumentException("Processing guarantee " + guarantees + " not supported by this broker version");

boolean isSupportedGuarantee(FunctionConfig.ProcessingGuarantees g) {
    return g == FunctionConfig.ProcessingGuarantees.ATMOST_ONCE
        || g == FunctionConfig.ProcessingGuarantees.ATLEAST_ONCE
        || g == FunctionConfig.ProcessingGuarantees.EFFECTIVELY_ONCE;
}

try {
    ProcessingGuarantees pg = FunctionCommon.convertProcessingGuarantee(config.getProcessingGuarantees());
} catch (RuntimeException e) {
    log.error("Unrecognized processing guarantee: " + config.getProcessingGuarantees(), e);
    throw new IllegalArgumentException("Use ATMOST_ONCE, ATLEAST_ONCE, or EFFECTIVELY_ONCE", e);
}

When it happens

Trigger: Calling convertProcessingGuarantee with a FunctionConfig.ProcessingGuarantees value whose name() has no internal counterpart — e.g. a new enum constant (such as an added delivery mode) written by a newer client and read by an older utils build.

Common situations: Mixed-version deployments where the public config enum gained a constant first; hand-edited function configs; tooling that serializes an enum from a newer Pulsar client into worker configs.

Related errors

• Unknown producer crypto failure action
• Unknown consumer crypto failure action
• Unrecognized runtime:
• Unknown producer protobuf failure action
• Unknown consumer protobuf failure action

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