> ## Documentation Index > Fetch the complete documentation index at: https://docs.streamnative.io/llms.txt > Use this file to discover all available pages before exploring further. # Troubleshoot the Kafka Schema Registry > Error codes, what causes them, and how to fix them—plus the silent failures that produce no error at all. ## Error codes | Code | Message | Cause | Fix | | --------- | ---------------------------- | ------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **401** | Missing AUTHORIZATION header | No credentials sent, or a scheme other than `Basic` or `Bearer`. | Set `basic.auth.credentials.source` and `basic.auth.user.info`, or use `curl -u`. See [Connect](/kafka/governance/sr/connect#authenticate). | | **403** | Role cannot access... | The identity authenticated but lacks permission on the subject. | Assign the right role. A producer needs `schema-writer`; a consumer needs `schema-reader`. See [Security](/kafka/governance/sr/fundamentals/security#authorization). | | **404** | Not found | The endpoint isn't implemented, or the subject, version, or ID doesn't exist. | Check it against the [supported endpoint list](/kafka/governance/sr/reference/confluent-compatibility#supported-endpoints) before assuming the resource is missing. | | **40401** | Subject not found | The subject has no versions, or every version is soft-deleted. | Retry with `?deleted=true` to see whether it was deleted rather than never created. | | **40402** | Version not found | The version doesn't exist under that subject. | List versions with `GET /subjects/{subject}/versions`. | | **40403** | Schema not found | No schema with that ID. | Check the ID—a client cache can hold a stale one. | | **40404** | Subject already soft-deleted | You soft-deleted it twice. | If you meant to remove it, use `?permanent=true`. | | **40405** | Subject not soft-deleted | Hard delete attempted without a soft delete first. | Soft delete, then repeat with `?permanent=true`. | | **40406** | Version already soft-deleted | Same as 40404, for a version. | Use `?permanent=true`. | | **40407** | Version not soft-deleted | Same as 40405, for a version. | Soft delete first. | | **409** | Incompatible schema | The new schema fails the subject's compatibility check, **or** it changes the subject's format. | Run the [compatibility check](/kafka/governance/sr/fundamentals/schema-evolution#test-a-schema-before-you-register-it) with `?verbose=true` to see why. A format change needs a new subject. | | **412** | N/A | The `Accept` header isn't one the registry supports. | Use `application/vnd.schemaregistry.v1+json` or `application/json`. | | **42201** | Invalid schema | The schema doesn't parse or fails validation for its type. | Validate it locally against the format's specification first. | | **42206** | Reference exists | Another schema references the one you're deleting. | Use `GET /subjects/{s}/versions/{v}/referencedby` to find them and delete those first. | | **42208** | Invalid subject | The subject name is empty, over 249 characters, or contains characters outside `[a-zA-Z0-9._-]`. | Rename the subject. See [Subject names and Pulsar coordinates](/kafka/governance/sr/fundamentals/key-concepts#subject-names-and-pulsar-coordinates). | ## 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](/kafka/governance/sr/reference/confluent-compatibility#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](/kafka/governance/sr/connect#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](/kafka/governance/sr/fundamentals/key-concepts#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](/kafka/governance/sr/fundamentals/serdes#subject-name-strategies)—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](/kafka/governance/sr/manage/manage-schemas#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](/cookbook/kafka-schema-registry-geo-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](/kafka/governance/sr/fundamentals/schema-references). ## Next steps Every behavior difference in one place. Worked calls for diagnosing from the command line.