Start with the symptom, then take the safest check.
Do not reinstall the agent or rotate a key until the evidence points there. Most issues belong to one of three layers: browser/API, platform-to-database, or agent-to-platform.
Four checks before changing anything
kubectl config current-context kubectl get pods -n krevopilot-system kubectl logs deployment/krevopilot-agent -n krevopilot-system --tail=50
“Request failed: 502”
Platform/API pathA 502 means the web proxy could not get a valid response from the backend. It does not prove that the cluster or agent is offline.
- Retry once after 30–60 seconds.
- Check the platform status and whether login, Clusters and another API-backed page fail too.
- If you operate the deployment, inspect web proxy and backend health, container logs, database reachability and recent deploys.
- Keep the last stored cluster snapshot visible with a “platform temporarily unavailable” state instead of showing first-time onboarding.
Rotating the cluster key cannot repair a failed backend or reverse proxy.
“Snapshot rejected” or command poll 401
Agent identityThe platform rejected the agent credentials. Common causes are an expired/rotated key, a key copied from another saved cluster record, or a cluster alias that does not match the generated command.
- Open the existing saved cluster row in KrevoPilot.
- Select Fix connection and generate a new key.
- Run the generated reconnect command in that exact cluster.
- Verify logs show
Snapshot accepted id=....
Do not create a new cluster record unless this is genuinely a different cluster.
Cluster is offline, setup incomplete or has no data
| UI state | Meaning | Next action |
|---|---|---|
| Setup incomplete | No accepted report has ever arrived. | Finish installation and inspect agent logs. |
| Offline / not reporting | A previous report exists, but heartbeat is stale. | Check cluster, agent pod and outbound network. |
| Live, no snapshot | Heartbeat exists but retained data is unavailable or still processing. | Wait one interval, refresh and inspect acceptance logs. |
Stored historical data should remain visible when available. An offline agent pauses new monitoring; it does not mean KrevoPilot changed the cluster.
Helm conflict on .data.agent-key
This usually means another tool such as kubectl replace owns the Secret field that Helm is trying to manage.
kubectl get secret krevopilot-agent -n krevopilot-system -o jsonpath="{.metadata.managedFields[*].manager}"
kubectl get secret krevopilot-agent -n krevopilot-system -o yaml- Record field managers and Secret metadata. Do not share the encoded key.
- Use KrevoPilot’s generated upgrade/reconnect command, including the current key when the app requires one.
- If ownership still conflicts, stop and repair field ownership under your Kubernetes change process or contact support with redacted metadata.
Deletion may interrupt a working agent and lose the only stored key reference. The correct repair depends on the field manager and Helm version.
Loki is not detected
- Confirm Loki is installed and its Service exists in the selected cluster.
- Check service name, namespace, port, scheme and tenant/auth requirements.
- From an authorized pod, verify the configured URL resolves and reaches Loki.
- Return to Settings → Integrations, refresh detection and test the connection.
kubectl get service -A | findstr /I loki kubectl get pods -A | findstr /I loki
Without detected Loki, current pod logs may still be available on demand, but historical log querying is not.
Optimize keeps loading or shows no recommendations
- Confirm the same cluster is selected on Overview and Optimize.
- Check that agent timestamps and metric samples continue to advance.
- Minimum recommendation history is 72 hours; 7 days is the normal confidence target.
- Workloads with changed requests/limits restart learning for the new configuration epoch.
- Idle workloads are reviewed separately rather than receiving an unsafe zero request.
Overview and Optimize must use the same backend analysis. If one says zero while the other shows measured reclaimable resources, capture both timestamps and report it as a consistency defect.
“Application name unavailable”, aliases or duplicate rows
Exact names may be hidden by identifier privacy settings. A duplicate real-name and alias row means historical identity migration has not merged the old alias series with the current real-name series.
- Confirm the agent is current and identifier collection matches workspace policy.
- Do not delete metric rows manually.
- Run the supported identity-backfill dry run against the production database.
- Review every planned alias-to-real-name merge and ambiguous skip.
- Back up the database before applying the approved tenant-scoped merge.
After a correct migration, workload count, maturity clock and savings should no longer be double-counted.
SSO: unknown workspace or no account exists
| Error | Likely cause | Fix |
|---|---|---|
| Unknown workspace | The generic login route cannot identify which tenant’s OIDC config to use. | Use the workspace-specific sign-in URL or choose the workspace before redirect. |
| No account exists | Automatic provisioning is off and the email was not pre-created. | Invite/create the member, or enable controlled provisioning for the company domain. |
| Redirect mismatch | The provider callback differs from the exact URL shown in settings. | Register the exact HTTPS callback, with no added slash or alternate host. |
Do not use public domains such as gmail.com for production auto-provisioning. After first sign-in, assign the member to the correct team and clusters.
Metrics or recommendations are unavailable
KrevoPilot needs resource metrics from the cluster. Confirm Metrics Server or the supported metric source is healthy and that the agent can read it.
kubectl top nodes kubectl top pods -A
If these fail, repair the cluster metric source first. If they work but KrevoPilot samples do not advance, inspect agent RBAC and logs.