{"record":{"id":"5660872b3bff561e","repo":"apache/pulsar","slug":"metadata-has-a-max-size-of-maxconsumermetadatasi","errorCode":null,"errorMessage":"metadata has a max size of + maxConsumerMetadataSize +  bytes","messagePattern":"metadata has a max size of \\+ maxConsumerMetadataSize \\+  bytes","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"pulsar-common/src/main/java/org/apache/pulsar/common/naming/Metadata.java","lineNumber":40,"sourceCode":"\n/**\n * Validator for metadata configuration.\n */\npublic class Metadata {\n\n    private Metadata() {}\n\n    public static void validateMetadata(Map<String, String> metadata,\n                                        int maxConsumerMetadataSize) throws IllegalArgumentException {\n        if (metadata == null) {\n            return;\n        }\n\n        int size = 0;\n        for (Map.Entry<String, String> e : metadata.entrySet()) {\n            size += (e.getKey().length() + e.getValue().length());\n            if (size > maxConsumerMetadataSize) {\n                throw new IllegalArgumentException(getErrorMessage(maxConsumerMetadataSize));\n            }\n        }\n    }\n\n    private static String getErrorMessage(int maxConsumerMetadataSize) {\n        return \"metadata has a max size of \" + maxConsumerMetadataSize + \" bytes\";\n    }\n}\n","sourceCodeStart":22,"sourceCodeEnd":49,"githubUrl":"https://github.com/apache/pulsar/blob/820761864ed8e2a7d2e52dd9763ad2ae117c1395/pulsar-common/src/main/java/org/apache/pulsar/common/naming/Metadata.java#L22-L49","documentation":"Metadata.validateMetadata sums the character lengths of all keys and values in a consumer metadata map and throws IllegalArgumentException when the total exceeds maxConsumerMetadataSize. The error message reports the configured maximum size in bytes.","triggerScenarios":"Calling Metadata.validateMetadata (directly or via consumer creation APIs) with a properties/metadata map whose combined key+value character lengths exceed the configured limit (char count, not UTF-8 bytes, so multibyte chars can trip it sooner in bytes).","commonSituations":"Consumers attaching large key/value metadata (tracing ids, ownership tags) to subscriptions; many small entries accumulating past the cap; oversized tenant-supplied labels.","solutions":["Reduce the number and size of metadata keys/values attached to the consumer","Raise maxConsumerMetadataSize via its configuration if the larger payload is intended","Encode or shorten values (e.g. hash long ids instead of embedding them)"],"exampleFix":"// before\nMap<String, String> meta = Map.of(\"owner\", veryLongOwnershipString); // exceeds limit\n// after\nMap<String, String> meta = Map.of(\"ownerHash\", sha256Short(veryLongOwnershipString));","handlingStrategy":"validation","validationCode":"int max = 5000; // mirror configured maxConsumerMetadataSize\nint size = 0;\nfor (Map.Entry<String, String> e : metadata.entrySet()) {\n    size += e.getKey().length() + e.getValue().length();\n}\nif (size > max) {\n    throw new IllegalArgumentException(\"Consumer metadata too large: \" + size + \" > \" + max + \" chars\");\n}","typeGuard":null,"tryCatchPattern":"try {\n    Metadata.validateMetadata(metadata, maxConsumerMetadataSize);\n} catch (IllegalArgumentException e) {\n    metadata = compactMetadata(metadata); // trim/hash oversized values\n}","preventionTips":["Keep consumer metadata small and bounded (ids/hashes, not payloads)","Count multibyte characters carefully: lengths are chars, UTF-8 bytes may exceed them","Agree on a metadata schema/size budget across producer teams"],"tags":["metadata","validation","consumer","limit-exceeded"],"backgroundTag":"metadata-size-limit-exceeded","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"}