Skip to main content

​
SRP refuses to start

Symptom: The container exits immediately at startup. Cause: A required setting is missing — SRP refuses to start without a valid license or an explicit authentication provider. Fix:
  1. Set CDK_LICENSE to a valid Conduktor Scale or Gateway license. Note that the license is only checked at startup: a running proxy keeps serving after its license expires, but the next restart fails. Alert on the license_expiry_timestamp_seconds metric to catch this before a restart.
  2. Set AUTH_PROVIDER explicitly — it has no default.
  3. Review the startup logs: the error names the missing setting.

​
SRP not discovered by Console

Symptom: The SRP instance does not appear in the Console Schema Registry dropdown. Cause: Console is not receiving heartbeats from SRP. Fix:
  1. Verify CDK_SCHEMAREGISTRYPROXY_ENABLED=true is set on Console.
  2. Check that KAFKA_HEARTBEAT_ENABLED=true on SRP (this is the default).
  3. Confirm SRP and Console connect to the same Kafka cluster.
  4. Verify the _conduktor_srp_events topic exists and is accessible.

​
Permissions not applied

Symptom: Users receive authorization errors even after permissions are granted in Console. Cause: SRP is not consuming permission updates from Kafka. Fix:
  1. Check that AUTHORIZATION_MODE=reactive on SRP (this is the default). Permissions granted in Console only apply in reactive mode.
  2. Verify the _conduktor_srp_commands topic exists with the expected replication factor.
  3. Confirm Console is connected to the same Kafka cluster as SRP.
  4. Review SRP logs for permission consumption messages.

​
Authentication failures

Symptom: Clients receive 401 Unauthorized responses. Cause: JWT token validation is failing. Fix:
  1. Verify the JWKS endpoint is accessible from the SRP container.
  2. Confirm JWT_SUBJECT_CLAIM_NAME matches the claim used in your tokens.
  3. Check token expiration — set JWT_VALIDATE_EXPIRATION=false temporarily to isolate the issue.
With AUTH_PROVIDER=basic, also check that the credentials file is mounted at BASIC_AUTH_LOCATION (default /etc/srp/basic-auth.json, and it has to be an absolute path), that passwords are bcrypt hashes (plaintext is rejected unless BASIC_AUTH_ALLOW_PLAINTEXT=true) and that recently rotated credentials have had BASIC_AUTH_RELOAD_INTERVAL (default 30s) to be picked up. Note that 401 means authentication failed (bad or missing credentials), while 403 means the caller authenticated fine but the operation was denied by authorization.

​
Basic auth credential changes not picked up

Symptom: You edited the credentials file but the proxy keeps accepting the old passwords (or rejecting the new user), with no reload logged. Cause: The single credentials file is bind-mounted, so the container is bound to the file’s inode. Editors (vim, VS Code, IntelliJ), sed -i, mv and git checkout replace the file with a new inode — the container keeps reading the copy it started with. Fix:
  1. Write the file in place (cat new.json > basic-auth.json or tee) instead of replacing it, or mount the parent directory (- ./conf:/etc/srp:ro) so the filename is re-resolved on every read.
  2. Restart the proxy container to rebind the mount if the inode has already changed.
  3. Watch the basic_auth_credentials_reload_total{result="failure"} metric: failures mean the file on disk and the credentials in force have drifted apart. A malformed file is never applied — the last good snapshot keeps serving until the file parses again.

​
Producer denied in topic ACL mode despite a WRITE ACL

Symptom: With AUTHORIZATION_MODE=topic-acl, a producer registers schemas but gets 403 when fetching them. Cause: In topic ACL mode, Write does not imply Read. Fetching schemas requires a READ (or ALL) ACL on the subject’s topic. Fix: Grant the producer principal READ or ALL on the topic, or list the service account in AUTHORIZATION_SUPER_USERS if it is a break-glass identity. Also check that the authenticated identity matches the Kafka ACL principal name: the proxy checks it as User:{name}, where {name} is the identity extracted by the authentication provider (for JWT, the JWT_SUBJECT_CLAIM_NAME claim).

​
Requests return 404 for admin endpoints

Symptom: Deletes, PUT/DELETE on /config or /mode, or /exporters calls return 404 through the proxy but work against the Schema Registry directly. Cause: This is by design. SRP only proxies the endpoints application clients and read-only tooling use — administrative operations are not routed. For administrative work, use Conduktor Console, which connects to the Schema Registry directly.