{"record":{"id":"12bccf3757ead534","repo":"apache/pulsar","slug":"retain-key-ordering-cannot-be-altered-12bccf","errorCode":null,"errorMessage":"Retain Key Ordering cannot be altered","messagePattern":"Retain Key Ordering cannot be altered","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"pulsar-functions/utils/src/main/java/org/apache/pulsar/functions/utils/SinkConfigUtils.java","lineNumber":702,"sourceCode":"                .equals(existingConfig.getProcessingGuarantees())) {\n            throw new IllegalArgumentException(\"Processing Guarantees cannot be altered\");\n        }\n        if (newConfig.getConfigs() != null) {\n            mergedConfig.setConfigs(newConfig.getConfigs());\n        }\n        if (newConfig.getSecrets() != null) {\n            mergedConfig.setSecrets(newConfig.getSecrets());\n        }\n        if (newConfig.getParallelism() != null) {\n            mergedConfig.setParallelism(newConfig.getParallelism());\n        }\n        if (newConfig.getRetainOrdering() != null && !newConfig.getRetainOrdering()\n                .equals(existingConfig.getRetainOrdering())) {\n            throw new IllegalArgumentException(\"Retain Ordering cannot be altered\");\n        }\n        if (newConfig.getRetainKeyOrdering() != null && !newConfig.getRetainKeyOrdering()\n                .equals(existingConfig.getRetainKeyOrdering())) {\n            throw new IllegalArgumentException(\"Retain Key Ordering cannot be altered\");\n        }\n        @SuppressWarnings(\"deprecation\")\n        boolean autoAckChanged = newConfig.getAutoAck() != null\n                && !newConfig.getAutoAck().equals(existingConfig.getAutoAck());\n        if (autoAckChanged) {\n            throw new IllegalArgumentException(\"AutoAck cannot be altered\");\n        }\n        if (newConfig.getResources() != null) {\n            mergedConfig\n                    .setResources(ResourceConfigUtils.merge(existingConfig.getResources(), newConfig.getResources()));\n        }\n        if (newConfig.getTimeoutMs() != null) {\n            mergedConfig.setTimeoutMs(newConfig.getTimeoutMs());\n        }\n        if (newConfig.getCleanupSubscription() != null) {\n            mergedConfig.setCleanupSubscription(newConfig.getCleanupSubscription());\n        }\n        if (!StringUtils.isEmpty(newConfig.getArchive())) {","sourceCodeStart":684,"sourceCodeEnd":720,"githubUrl":"https://github.com/apache/pulsar/blob/820761864ed8e2a7d2e52dd9763ad2ae117c1395/pulsar-functions/utils/src/main/java/org/apache/pulsar/functions/utils/SinkConfigUtils.java#L684-L720","documentation":"Thrown by SinkConfigUtils.validateUpdate when retainKeyOrdering is set and differs from the existing sink's value. Like retainOrdering, key ordering is fixed at creation and cannot be changed through the update path.","triggerScenarios":"Updating a sink with getRetainKeyOrdering() non-null and different from the deployed config's value.","commonSituations":"Enabling per-key ordering on an already deployed sink via update; a config template with retainKeyOrdering enabled is reused to update a sink created without it.","solutions":["Keep retainKeyOrdering identical to the existing sink's value (or null)","Delete and recreate the sink if key ordering must change","Verify the deployed value via 'pulsar-admin sinks get' before updating"],"exampleFix":"// before\nsinkConfig.setRetainKeyOrdering(true); // deployed sink has false\nadmin.sinks().updateSink(tenant, namespace, sinkConfig, null);\n// after\nsinkConfig.setRetainKeyOrdering(false); // matches existing\nadmin.sinks().updateSink(tenant, namespace, sinkConfig, null);","handlingStrategy":"validation","validationCode":"if (newCfg.getRetainKeyOrdering() != null\n    && !newCfg.getRetainKeyOrdering().equals(existing.getRetainKeyOrdering())) {\n    throw new IllegalArgumentException(\"retainKeyOrdering is immutable\");\n}","typeGuard":null,"tryCatchPattern":"try {\n    admin.sinks().updateSink(tenant, namespace, cfg, null);\n} catch (IllegalArgumentException e) {\n    if (e.getMessage().contains(\"Retain Key Ordering cannot be altered\")) { /* revert retainKeyOrdering */ }\n    else throw e;\n}","preventionTips":["Leave retainKeyOrdering null on updates","Recreate the sink if key ordering must change","Document ordering decisions at creation time"],"tags":["pulsar","functions","config-validation","immutable-field"],"backgroundTag":"immutable-config-field-update","analyzedSha":"820761864ed8e2a7d2e52dd9763ad2ae117c1395","analyzedAt":"2026-09-06T00:14:20.138Z","contentChangedAt":"2026-09-06T00:14:20.138Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}