Diagnose problems

edka diagnose reads what Edka records about a deployment and what runs for it in the cluster, and reports what is wrong with the commands to run next. Clusters, apps, previews, databases and cron jobs have a diagnose of their own. Every diagnose only reads, and changes nothing.

Prerequisites

• The Edka CLI, signed in with edka login.

Diagnose a deployment

edka diagnose api

The command reads the deployment’s rollout, its pods, the Kubernetes events, its last five revisions, and the log of its failing pod. It prints each problem, then what it read:

$ edka diagnose api
✗ Pod api-x2k starts and exits, 4 times so far.
  back-off 5m0s restarting failed container
  Next: Read what it printed last, under Logs.
  Next: edka logs api --pod api-x2k --previous --tail 200
  Next: edka rollback api --generation 4

Deployment   api
Cluster      production
Namespace    default
Status       deploying
Image        ghcr.io/acme/api:v3
Revision     generation 5 (applied 5, healthy 4)
Rollout      failed: CrashLoopBackOff: back-off 5m0s restarting failed container
Replicas     1/2 ready, 1 updated, 1 available

POD       STATUS    READY   RESTARTS   REASON
api-7d9   running   true    0          —
api-x2k   failed    false   4          CrashLoopBackOff

Logs of api-x2k, from the container before its last restart
listening on :8080
panic: DATABASE_URL is not set

It finds these causes:

• an image the cluster can’t pull, or an image name Kubernetes refuses;
• a container that exits, or that is killed for exceeding its memory limit;
• a Secret or ConfigMap the pod names and the cluster lacks;
• a pod that no node can run, and a volume that can’t be mounted;
• a health check that fails;
• a change that failed and that Edka rolled back, is rolling back, or could not roll back;
• a failed last build of a Git deployment;
• a cluster Edka can’t read.

The log is the failing pod’s, from the container before its last restart when it restarted. --tail sets its length, 30 lines by default. A health check that fails while the rollout still runs is a note, since it may pass once the container is up.

Without a deployment, in the argument, --deployment or the directory link, edka diagnose diagnoses the cluster instead, like edka clusters diagnose.

Diagnose a cluster

edka clusters diagnose production

The command reads whether Edka reaches the cluster’s Kubernetes API, Edka’s last check of the node pools, the status of each deployment, the pods that fail, and the warnings Kubernetes recorded:

$ edka clusters diagnose production
✗ Node production-pool-workers-worker2 is not ready.
  Next: edka nodepools list --cluster production
  Next: edka api clusters drift repair-plan get production
✗ Deployment api is failing.
  CrashLoopBackOff: back-off 5m0s restarting failed container
  Next: edka diagnose api --cluster production
✗ Pod kube-system/coredns-1 is failing.
  coredns: ImagePullBackOff

Cluster        production
Status         active
Provider       hetzner
Location       fsn1
Kubernetes     v1.33.1+k3s1
Connectivity   connected
Workers        3/3
Node pools     drifted, checked 2026-10-02 11:00
Deployments    1 deployed, 1 failed

NAMESPACE     POD           PROBLEM    RESTARTS   MESSAGE
prod          api-7d9-x2k   crashing   12         app: CrashLoopBackOff - back-off 5m0s restarting failed container
kube-system   coredns-1     error      0          coredns: ImagePullBackOff

It finds these causes:

• a cluster that failed, with the last message Edka recorded for it;
• a Kubernetes API that Edka can’t reach, with what Edka found when it investigated and the action it suggests;
• a node that is not ready, a server that did not join, and a node pool with more or fewer servers than it is set to;
• a deployment that fails or that the cluster lacks;
• a pod that crashes, can’t start, is pending, or failed.

Diagnose apps, previews, databases and cron jobs

edka apps diagnose strapi
edka previews diagnose 12
edka databases diagnose orders
edka cronjobs diagnose nightly-report

Command	Reads	Finds
apps diagnose	The installed app, its pods, the events and the log of its failing pod	The pod causes of a deployment, and an install, update or uninstall that failed, with Edka’s message
previews diagnose	The preview, its rollout, pods, events and the log of its failing pod	The pod causes of a deployment, and a preview that failed, with the error Edka recorded
databases diagnose	The database, its instances, the conditions and warnings its operator reports, and its backups	An instance that is not ready, a write-ahead log that isn’t archived, a last backup that failed, and a database Edka failed to provision
cronjobs diagnose	The cron job, its last five runs and its events	A last run that failed, with its warning and log, a run Kubernetes could not start or schedule, and a change to the cron job that failed

While Edka still installs an app, provisions a database, or builds a preview, what is not ready yet is a note, not a problem.

Use the result in a script

A diagnose exits with 1 when it finds a problem, after the report, and with 0 when it finds none. When it can’t read a source, such as the events of a cluster that doesn’t answer, it names the source on stderr and reports the rest.

With --json, stdout has healthy, findings and unread, and what the command read. Each finding has problem, summary, detail and next, the commands to run next:

edka diagnose api --json | jq '.findings[].next'

When a rollout that --wait follows fails, the error names the edka diagnose command for the deployment. A failed apps install --wait or apps update --wait names edka apps diagnose, and a failed clusters create --wait names edka clusters diagnose.

Check the CLI itself

edka doctor checks the CLI rather than your infrastructure: the configuration and profile, the project link, the API and its sign-in discovery, your identity, and the cluster in context.

edka doctor

It prints the reason for each check that fails and exits with 1. With --json, the reason is in each check’s detail.