{"record":{"id":"bf935c3873464241","repo":"apache/pulsar","slug":"unrecognized-processing-guarantee","errorCode":null,"errorMessage":"Unrecognized processing guarantee: ","messagePattern":"Unrecognized processing guarantee: ","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"pulsar-functions/utils/src/main/java/org/apache/pulsar/functions/utils/FunctionCommon.java","lineNumber":189,"sourceCode":"    public static FunctionConfig.Runtime convertRuntime(Runtime runtime) {\n        for (FunctionConfig.Runtime type : FunctionConfig.Runtime.values()) {\n            if (type.name().equals(runtime.name())) {\n                return type;\n            }\n        }\n        throw new RuntimeException(\"Unrecognized runtime: \" + runtime.name());\n    }\n\n    public static ProcessingGuarantees convertProcessingGuarantee(\n            FunctionConfig.ProcessingGuarantees processingGuarantees) {\n        for (ProcessingGuarantees type :\n                ProcessingGuarantees\n                .values()) {\n            if (type.name().equals(processingGuarantees.name())) {\n                return type;\n            }\n        }\n        throw new RuntimeException(\"Unrecognized processing guarantee: \" + processingGuarantees.name());\n    }\n\n    public static FunctionConfig.ProcessingGuarantees convertProcessingGuarantee(\n            ProcessingGuarantees processingGuarantees) {\n        for (FunctionConfig.ProcessingGuarantees type : FunctionConfig.ProcessingGuarantees.values()) {\n            if (type.name().equals(processingGuarantees.name())) {\n                return type;\n            }\n        }\n        throw new RuntimeException(\"Unrecognized processing guarantee: \" + processingGuarantees.name());\n    }\n\n    public static TypeDefinition getSourceType(String className, TypePool typePool) {\n        return getSourceType(typePool.describe(className).resolve());\n    }\n\n    public static TypeDefinition getSourceType(TypeDefinition sourceClass) {\n        if (sourceClass.asErasure().isAssignableTo(Source.class)) {","sourceCodeStart":171,"sourceCodeEnd":207,"githubUrl":"https://github.com/apache/pulsar/blob/820761864ed8e2a7d2e52dd9763ad2ae117c1395/pulsar-functions/utils/src/main/java/org/apache/pulsar/functions/utils/FunctionCommon.java#L171-L207","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Upgrade broker/functions-worker to a version whose ProcessingGuarantees enum includes the config's value","Use supported guarantees: ATMOST_ONCE, ATLEAST_ONCE, or EFFECTIVELY_ONCE","Regenerate the config with a client version matching the server"],"exampleFix":"// before\n\"processingGuarantees\": \"PIPELINED\" // unrecognized\n// after\n\"processingGuarantees\": \"EFFECTIVELY_ONCE\"","handlingStrategy":"validation","validationCode":"Set<String> internal = Arrays.stream(ProcessingGuarantees.values())\n    .map(Enum::name).collect(Collectors.toSet());\nif (!internal.contains(guarantees.name()))\n    throw new IllegalArgumentException(\"Processing guarantee \" + guarantees + \" not supported by this broker version\");","typeGuard":"boolean isSupportedGuarantee(FunctionConfig.ProcessingGuarantees g) {\n    return g == FunctionConfig.ProcessingGuarantees.ATMOST_ONCE\n        || g == FunctionConfig.ProcessingGuarantees.ATLEAST_ONCE\n        || g == FunctionConfig.ProcessingGuarantees.EFFECTIVELY_ONCE;\n}","tryCatchPattern":"try {\n    ProcessingGuarantees pg = FunctionCommon.convertProcessingGuarantee(config.getProcessingGuarantees());\n} catch (RuntimeException e) {\n    log.error(\"Unrecognized processing guarantee: \" + config.getProcessingGuarantees(), e);\n    throw new IllegalArgumentException(\"Use ATMOST_ONCE, ATLEAST_ONCE, or EFFECTIVELY_ONCE\", e);\n}","preventionTips":["Only set ATMOST_ONCE, ATLEAST_ONCE, or EFFECTIVELY_ONCE in function configs","Keep CLI, client, and worker on matching Pulsar versions","Round-trip test all ProcessingGuarantees constants after upgrades","Reject unknown guarantee values during config validation before submission"],"tags":["enum","processing-guarantees","mapping","version-compatibility"],"backgroundTag":"unsupported-enum-value","analyzedSha":"820761864ed8e2a7d2e52dd9763ad2ae117c1395","analyzedAt":"2026-09-06T00:14:20.138Z","contentChangedAt":"2026-09-06T00:14:20.138Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}