Troubleshooting and support
Most issues come from the network path between KCM and Kafka, from certificates, or from the reverse proxy in front of KCM. Start with the API log.
Read the logs
# Docker Compose
docker logs -f kcm-api
# Kubernetes
kubectl -n kcm logs deploy/kcm-api -f
kubectl -n kcm logs deploy/kcm-ui -f
kubectl -n kcm get pods,svc,pvc,ingress
Connection tests of clusters, registries and Connect clusters log the full error, including the real certificate error.
A cluster does not connect
- Use Test connection in the cluster form: it shows the error from the brokers.
- Check that the API host or pod can reach every broker address advertised by Kafka, not only the bootstrap servers.
- Check the security protocol, the SASL mechanism and the credentials.
- For TLS, upload the truststore of the brokers in the cluster form.
# From the API container or pod
nc -vz broker-1.example.internal 9093
openssl s_client -connect broker-1.example.internal:9093 -servername broker-1.example.internal </dev/null
Certificate errors with Schema Registry, Kafka Connect, ksqlDB or Confluent Cloud
These connections verify certificates and host names. If they use a self-signed or private CA certificate, or if KCM runs behind a TLS inspecting proxy, add the root CA in Settings > Trusted certificates. It applies at once, without restart, to every HTTPS call of KCM.
Live views disconnect
- The reverse proxy must allow WebSocket upgrades on
/ws/v1and keep connections open: see the Ingress annotations in Install. KCM_REDIRECT_ALLOWLISTmust list the origin of the console (for examplehttps://kcm.example.com), otherwise the live consumer refuses the browser.ui.runtimeConfig.wsUrlmust usewss://when the console is served over HTTPS.
kubectl -n kcm describe ingress kcm
SSO sign in fails
- The redirect URI registered at the identity provider must be exactly
https://<host>/login/oauth2/code/{registrationId}(OIDC) orhttps://<host>/login/saml2/sso/{registrationId}(SAML), and these paths must reach the API. With the Helm chart, use chart 1.5.1 or later, which routes them through its Ingress; with your own Ingress, see the SSO paths. - The identity provider must send an email address.
- A first SSO sign in needs a free seat.
- An error about the redirect means the console origin is missing from
KCM_REDIRECT_ALLOWLIST.
"Too many failed sign in attempts"
The sign in is locked for KCM_LOGIN_LOCK_MINUTES (15 by default) after repeated failures. Wait, or
sign in from another address if only one address is locked. A user who lost their authenticator app can use a
recovery code, or ask an administrator to reset the second factor. See
Sign in, 2FA and SSO.
Forbidden errors
- Check the roles and grants of the user in My profile (the user) or Settings > Users (an administrator).
- Ask the API why:
GET /api/v1/authz/explain, see Roles and access control. - A read-only service account token refuses every change.
- A
409withKCM-1006means the object is managed by KCM as code: change its declaration instead.
"Your license allows..." or additions are blocked
You reached a quota of your edition, or your license allows fewer resources than configured (for example after the trial). Everything keeps running; remove the extra resources named in the banner, or upgrade. See Editions and licensing.
Stored passwords no longer work after a restore or a move
The encryption key pair is not the one that encrypted the database. The API log lists the secrets it cannot decrypt. Restore the key pair saved with the database, or enter those secrets again. See Upgrades and backups.
Get help
- Email: support@kcmhub.io (standard email support from Starter, SLA and priority support with Enterprise).
- Community: GitHub Discussions and issues on github.com/kcmhub/KCM.
- the KCM version (shown in the header of the console) and the edition;
- Docker Compose, or Kubernetes version and distribution, Ingress controller,
helm version; - the API log around the time of the failure, without secrets.