# org.apache.kafka.common.errors.PrincipalDeserializationException: Failed to deserialize principal from bytes

- **ID:** `kafka/principal-deserialization-failure`
- **Domain:** kafka
- **Category:** auth_error
- **Verification:** ai_generated
- **Fix Rate:** 78%

## Root Cause

Kafka broker cannot deserialize the principal object from the authentication token, often due to a custom principal builder class not being available or incompatible serialization format.

## Version Compatibility

| Version | Status | Introduced | Deprecated |
|---------|--------|------------|------------|
| kafka_2.13-3.4.0 | active | — | — |
| kafka_2.13-3.5.1 | active | — | — |
| kafka_2.13-3.6.0 | active | — | — |

## Workarounds

1. **Add the custom principal builder JAR to the Kafka broker classpath (e.g., in `libs/` directory) and verify the `principal.builder.class` property in `server.properties` matches the fully qualified class name.** (85% success)
   ```
   Add the custom principal builder JAR to the Kafka broker classpath (e.g., in `libs/` directory) and verify the `principal.builder.class` property in `server.properties` matches the fully qualified class name.
   ```
2. **If using SASL/PLAIN, switch to a simpler authentication mechanism that uses the default principal builder, e.g., set `sasl.enabled.mechanisms=PLAIN` and `principal.builder.class=org.apache.kafka.common.security.authenticate.DefaultPrincipalBuilder` in `server.properties`, then restart brokers.** (75% success)
   ```
   If using SASL/PLAIN, switch to a simpler authentication mechanism that uses the default principal builder, e.g., set `sasl.enabled.mechanisms=PLAIN` and `principal.builder.class=org.apache.kafka.common.security.authenticate.DefaultPrincipalBuilder` in `server.properties`, then restart brokers.
   ```
3. **Ensure the custom principal builder class implements `org.apache.kafka.common.security.auth.PrincipalBuilder` and is serializable; recompile with the same Kafka version as the broker.** (90% success)
   ```
   Ensure the custom principal builder class implements `org.apache.kafka.common.security.auth.PrincipalBuilder` and is serializable; recompile with the same Kafka version as the broker.
   ```

## Dead Ends

- **** — The missing custom principal builder class is not loaded at startup; restarting does not add it to the classpath. (95% fail)
- **** — The issue is in the deserialization code, not in persisted data; clearing logs removes data but does not fix the class loading. (90% fail)
- **** — If the authentication token was serialized with a custom builder, the default builder cannot deserialize it, causing the same error. (80% fail)