{"record":{"id":"56d53162bebba3b4","repo":"apache/pulsar","slug":"payload-payloadsize-bytes-cannot-be-decoded-w","errorCode":null,"errorMessage":"payload (${payloadSize} bytes) cannot be decoded with schema ${schema}","messagePattern":"payload \\((.+?) bytes\\) cannot be decoded with schema (.+?)","errorType":"exception","errorClass":"SchemaSerializationException","httpStatus":null,"severity":"error","filePath":"pulsar-client/src/main/java/org/apache/pulsar/client/impl/MessageImpl.java","lineNumber":525,"sourceCode":"    }\n\n\n    private KeyValueSchemaImpl<?, ?> getKeyValueSchema() {\n        if (schema instanceof AutoConsumeSchema) {\n            return (KeyValueSchemaImpl<?, ?>) ((AutoConsumeSchema) schema).getInternalSchema(getSchemaVersion());\n        } else {\n            return (KeyValueSchemaImpl<?, ?>) schema;\n        }\n    }\n\n    private T decode(byte[] schemaVersion) {\n        try {\n            return decodeBySchema(schemaVersion);\n        } catch (ArrayIndexOutOfBoundsException e) {\n            // It usually means the message was produced without schema check while the message is not compatible with\n            // the current schema. Therefore, convert it to SchemaSerializationException with a better description.\n            final int payloadSize = payload.readableBytes();\n            throw new SchemaSerializationException(\"payload (\" + payloadSize + \" bytes) cannot be decoded with schema \"\n                    + new String(schema.getSchemaInfo().getSchema(), StandardCharsets.UTF_8));\n        }\n    }\n\n    private T decodeBySchema(byte[] schemaVersion) {\n        T value = poolMessage ? schema.decode(payload.nioBuffer(), schemaVersion) : null;\n        if (value != null) {\n            return value;\n        }\n\n        if (null == schemaVersion) {\n            return schema.decode(getByteBuffer());\n        } else {\n            return schema.decode(getByteBuffer(), schemaVersion);\n        }\n    }\n\n    private T decodeBySchemaId(byte[] schemaId) {","sourceCodeStart":507,"sourceCodeEnd":543,"githubUrl":"https://github.com/apache/pulsar/blob/820761864ed8e2a7d2e52dd9763ad2ae117c1395/pulsar-client/src/main/java/org/apache/pulsar/client/impl/MessageImpl.java#L507-L543","documentation":"When decoding a message payload with the consumer's schema, an ArrayIndexOutOfBoundsException from the underlying decoder usually means the message was produced without proper schema validation and its bytes don't fit the schema. MessageImpl.converts this into SchemaSerializationException with the payload size and schema info so the failure is diagnosable.","triggerScenarios":"Calling getValue(), getKeyValue(), or getKeyValueBySchemaVersion() on a message whose payload cannot be decoded by the resolved schema — typically messages written by an old/other producer with a different serialization (e.g. incompatible Avro record, JSON written without schema).","commonSituations":"Schema compatibility set too loosely (ALLOWED/always) allowing incompatible producers; a topic previously written with a different schema type (e.g. JSON then Avro); messages produced by non-Pulsar tools bypassing schema checks.","solutions":["Align the producer's schema with the consumer's schema (re-register compatible schema or fix the producer serialization).","Enable schema validation enforcement on the topic/policies so incompatible messages are rejected at publish time.","Read the message with Schema.BYTES/raw and deserialize manually if you must tolerate mixed payloads; or skip/dead-letter undecodable messages via catch of SchemaSerializationException."],"exampleFix":"// before\nMessage<MyPojo> msg = consumer.receive();\nMyPojo v = msg.getValue(); // throws\n// after\ntry {\n  MyPojo v = msg.getValue();\n} catch (PulsarClientException.SchemaSerializationException e) {\n  log.warn(\"Undecodable message: {}\", e.getMessage()); // dead-letter/skip\n}","handlingStrategy":"try-catch","validationCode":"// before consuming, ensure topic schema is compatible:\n// check topic schema version / compatibility policy via admin API against your Schema","typeGuard":null,"tryCatchPattern":"try {\n  T value = msg.getValue();\n} catch (PulsarClientException.SchemaSerializationException e) {\n  log.warn(\"Undecodable payload: {}\", e.getMessage());\n  // ack/skip or dead-letter the message\n}","preventionTips":["Enforce schema validation on topics (isAllowAutoUpdateSchema / compatibility checks).","Keep producer and consumer schema definitions versioned together.","Catch SchemaSerializationException in the consumer loop to avoid crash loops on poison messages."],"tags":["pulsar","schema","deserialization","compatibility"],"backgroundTag":"schema-serialization-failed","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"}