Skip to content
Percona Operators Documentation

Rate this page
☆ ☆ ☆ ☆ ☆
Thanks for your feedback
Thank you! The feedback has been submitted.

Get free database assistance or contact our experts for personalized support.

Get help from Percona

Troubleshoot connection issues

Use this page when your application cannot connect to Percona Server for MongoDB. For cluster or Operator issues (pods not starting, backups failing, and so on), see Troubleshooting.

Connection refused

Symptom: The driver reports “connection refused” or “ECONNREFUSED.”

Common causes:

  • Your app runs outside the cluster and you are using the internal hostname (for example my-cluster-name-mongos.default.svc.cluster.local). That hostname works only inside Kubernetes. Use port-forward for local dev or expose the cluster (NodePort or LoadBalancer) and use the external host and port in your URI.
  • Port-forward is not running. If you use port-forward, keep the kubectl port-forward command running while you connect.
  • Wrong port. Default MongoDB port is 27017. If you use NodePort, use the NodePort number in your URI.

Authentication failed

Symptom: “Authentication failed” or “auth failed.”

Common causes:

  • Wrong username or password. Get the credentials from the correct Secret. For the admin user, see Connection secrets. For an application user, see Get credentials for your app. Ensure there are no extra spaces when reading from the Secret (for example when using base64 --decode).
  • Wrong database in the URI. The user may be defined on the admin database; use /admin in the URI path (for example mongodb://user:pass@host/admin).
  • User does not exist yet. If you added a user in the Custom Resource, apply the change and wait for the Operator to create the user and Secret.

Wrong replica set name or hostname

Symptom: “No primary found” or “replica set name does not match.”

Common causes:

  • Replica set name missing or wrong. For a non-sharded cluster, the URI must include replicaSet=rs0 (for example .../admin?replicaSet=rs0). See Connect your application.
  • Sharded vs replica set. If the cluster is sharded (default), connect to the mongos host (<cluster-name>-mongos.<namespace>.svc.cluster.local), not the replica set host. If sharding is off, use the rs0 host and replicaSet=rs0.

Cannot resolve hostname

Symptom: “getaddrinfo ENOTFOUND” or “no such host.”

Common causes:

  • App runs outside the cluster. Internal DNS names (.svc.cluster.local) resolve only inside the cluster. Use Connect from your laptop or CI: port-forward (then use localhost in the URI) or expose the cluster and use the external hostname or IP.
  • Typo in cluster name or namespace. Check with kubectl get psmdb -A. Use the exact cluster name and namespace in the URI.

TLS/SSL errors

Symptom: SSL handshake or certificate errors.

Common causes:

  • The URI disagrees with the cluster about TLS. TLS is on by default (tls.mode: preferTLS), which accepts both TLS and plain connections - but a cluster set to requireTLS rejects a URI carrying ssl=false. Prefer the connection string from the Secret, which already matches the cluster; if you build the URI yourself, use ssl=true and make sure the client trusts the CA. See Transport encryption (TLS/SSL).
  • Wrong CA or certificate. For production, use the correct CA certificate or system trust store.
  • “No certificate provided by peer” even though the URI and cluster agree on TLS. The Operator’s default clusterAuthMode: x509 requires a client certificate for any TLS connection, not just internal replica-set traffic. This applies even under the default preferTLS mode, and isn’t configurable through the Custom Resource. See Connect with a client certificate, or connect without tls=true in the URI if a plain connection is acceptable.

More help

Next steps

What’s next for developers?

Last update: September 14, 2026
Created: February 13, 2026