Português Web version Download for Linux
Help

Troubleshooting

The common problems that get in the way (kubelogin, private clusters, metrics and Redis on Azure Cache) and how to fix them. Each feature page also lists its own errors.

Where
Web and Desktop
Plans
Free, Pro and Team
Role
Not applicable

“uses an exec plugin (kubelogin) — connect through the Cloud account tab”

On the web, a context that authenticates with an exec plugin only runs on your machine. For AKS (kubelogin) and EKS (aws), add the Azure or AWS account on the Cloud account tab and Kubepier discovers the cluster. For GKE (gke-gcloud-auth-plugin) and others, use a ServiceAccount token. On desktop, plugins work as they do in kubectl.

The CA or credential is in a local file

The web needs the content embedded in the kubeconfig. Generate a self-contained version:

kubectl config view --flatten --minify

The cluster does not respond on the web

  • The API only accepts some IPs: allow Kubepier’s egress IPs.
  • The cluster is fully private: the web cannot reach it. Use the desktop app through your VPN.

The Azure or AWS account finds no clusters

  • Azure: the Service Principal needs Reader and Azure Kubernetes Service Cluster User Role on the subscription or resource group; on AKS with Entra ID, also a role on the cluster, such as Azure Kubernetes Service RBAC Reader.
  • AWS: the IAM key needs eks:ListClusters and eks:DescribeCluster (ec2:DescribeRegions is optional), and the IAM user needs an EKS access entry to read the cluster.

Empty Secrets and Helm releases

The credential cannot read Secrets. The Kubernetes view role does not include Secrets, and the web reads Helm releases from Secrets labelled owner=helm.

No CPU and memory usage

On the web, the cluster has no metrics-server. On desktop, open the cluster Settings › Metrics and use Install / Update under Lens Metrics: Kubepier applies Prometheus, kube-state-metrics and node-exporter in the lens-metrics namespace and picks the Lens provider. Metrics show up in 1 to 2 minutes, once Prometheus is up. Uninstall asks for confirmation and deletes the lens-metrics namespace with all metrics history.

The action button shows a lock

The organization is on Free, or you are a member. Actions, shell and destructive actions on services need Pro or Team and the admin role (on desktop, from 2.7.0). On desktop, a paid licence not confirmed for more than 7 days counts as Free.

On desktop, the lock and the upgrade notice come with 2.4.0. Up to 2.3.0, the paid actions do not show on Free: the menu has only what the plan allows.

Redis on Azure Cache: WRONGPASS and "connection closed" on both routes

A real production case: a Redis on Azure Cache Premium showed conexao_encerrada on the Direct route and on the Through the cluster route. Firewall, port 6380 and TLS were right. The cause was the password saved on the client: the access key of another cache. Redis refused the AUTH and closed the connection, and Kubepier only showed the close.

redis-cli --tls -h <cache>.redis.cache.windows.net -p 6380 --askpass PING
  • Since 2026-10-05, the web shows the real error: WRONGPASS (wrong password) or NOAUTH (missing password) on the status, and "no permission on the service" on actions. On desktop, from 2.3.0; up to 2.2.0, this case shows as Connection is closed.
  • If the failure is the same on both routes, suspect the credential before the network: the two routes take different networks, but the password is the same.
  • Test the credential with the official client, as in the command below: the right answer is PONG; WRONGPASS confirms the wrong password.
  • To avoid mixing dev and prd, paste into the client form the whole connection string the portal shows under Access keys of the right cache (host:6380,password=...,ssl=True,abortConnect=False), instead of copying only the key.

A client service says "no permission"

  • RabbitMQ: management tag and read on the queues.
  • Service Bus: a SAS policy with Manage.
  • MongoDB: clusterMonitor on admin and read on the database.
  • Redis: the ACL commands on the Redis page (NOPERM). WRONGPASS or NOAUTH is not a missing permission: it is a wrong or missing password.

Warning when installing on Windows or macOS

The installer is not signed yet. On Windows, click “More info” and “Run anyway”. On macOS, right-click the app and choose “Open”.