Troubleshoot the Kafka Schema Registry

​

Error codes

​

Silent failures

These produce no error, which makes them the ones worth knowing about in advance.

​

Data Contract fields disappear

A registration carrying metadata or ruleSet succeeds. Those fields are discarded and the schema is stored without them, with no error and no warning. If you’re migrating from Confluent and depend on schema rules, CEL validation, or migration rules, they stop being enforced at the moment you switch clusters. See Unsupported features.

​

GET /config reports NONE

The global GET /config always returns {"compatibilityLevel":"NONE"} regardless of the real setting. The actual default is BACKWARD. Anything that reads the global config to decide whether compatibility is enforced will conclude it isn’t. Read GET /config/{subject} instead.

​

normalize does nothing for JSON Schema

?normalize=true is a no-op for JSON Schema. Two schemas differing only in property ordering are stored as two distinct schemas, each registration creating a new version. If a subject is accumulating versions that look identical, this is why. Serialize schemas deterministically before registering.

​

An empty subject list may mean no permission

GET /subjects filters to the subjects your credentials can read instead of returning 403. An empty array means either the registry is empty or your role covers none of the existing subjects. Check your role bindings before concluding the registry is empty.

​

Common symptoms

​

The consumer can’t deserialize records

Check, in order:

1. Registry credentials. A deserializer that can’t reach the registry fails on the first record. Confirm with curl -u "any-user:$API_KEY" "$SR_URL/schemas/types".
2. The /kafka suffix. On a Pulsar cluster the URL needs it; on a Kafka cluster it must not have it. See Get the Schema Registry URL.
3. Deserializer class. The format must match what the producer used.
4. schema-reader role covering the subject.

​

Records look like garbage in a console consumer

Expected. Every schematized record carries a 1-byte magic value and a 4-byte schema ID before the payload, so a plain console consumer shows those bytes as noise. Use a schema-aware consumer, or strip the 5-byte prefix. See The wire format.

​

The producer registers a subject nobody expected

Auto-registration is on by default, so the first producer to connect defines the subject. If a subject appeared with an unexpected name, check the producer’s subject name strategy—and note that RecordNameStrategy subjects are parsed as Pulsar tenant/namespace/topic. Turn auto-registration off for subjects that matter. See A workflow that holds up.

​

A schema registered moments ago isn’t visible

Clients cache schema lookups, including misses. Restart the client, or configure a cache expiry.

​

PUT /mode fails

Mode changes depend on how the registry is deployed for your cluster. On clusters that don’t support it, GET /mode always returns READWRITE and PUT /mode fails. IMPORT mode is normally set by Universal Linking replication, not by clients.

​

A schema over 5 MB is rejected

The request body limit is 5 MB, which is the effective maximum schema size. Split a schema that large using schema references.

​

Next steps