Troubleshoot a Deployment
When an application is not behaving, the platform gives you the same diagnostic signals, status, events, and logs, from the console, the astroctl CLI, or Nova. A healthy application reports Status: Healthy and Sync: Synced. Anything else is a starting point for the steps below.
Inspect an unhealthy application
Console
Open the application to reach every diagnostic signal in its detail view:
- Overview: status and sync state.
- Events: deployment events (the platform's view) and Kubernetes events (scheduling, image pulls, probes).
- Logs: logs across all pods for the application.
- Force Sync: re-sync when the desired spec is correct but the cluster has drifted or a sync is stuck.
CLI
-
Check status. Is it healthy, and is it synced?
astroctl app status myapp # live status (use --watch / -w to keep streaming)astroctl app get myapp # full detail, including endpoint and source -
Read the events. Events explain why a rollout is stuck, in two layers: deployment events (the platform's view) and Kubernetes events (the cluster's view).
astroctl app events myapp # deployment events (default)astroctl app events myapp --k8s # Kubernetes events (scheduling, image pulls, probes)Add
-wto stream events as they happen. -
Read the logs. Logs cover all pods for the application.
astroctl app logs myapp # follows by default (Ctrl-C to stop) -
Force a re-sync. If the desired spec is correct but the cluster has drifted or a sync is stuck:
astroctl app resync myapp
Nova
Ask in plain language, for example "why is myapp unhealthy?" or "show me the errors in myapp's logs." Nova reads the same status, deployment and Kubernetes events, and logs, then summarizes the likely cause and the next step, and can run a deeper cluster diagnosis if the issue is infrastructure-level.
Common issues
| Symptom | Likely cause | Where to look |
|---|---|---|
| Stuck not Synced | The platform cannot reconcile the spec yet, or the cluster lost contact | app events myapp; check the cluster is Connected (cluster management) |
| Pods ImagePullBackOff | Wrong image registry/repository/tag, or a private registry | app events myapp --k8s; verify the source.image values |
| Pods CrashLoopBackOff | The application is exiting on startup | app logs myapp for the crash reason |
| Pods Pending | The cluster does not have enough capacity for the requested resources | app events myapp --k8s; for image-source apps the requests come from the availability tier, and for helm/repository/yaml apps from your chart or manifest |
| App runs but not reachable | For the image source type, the app must listen on port 8080 (TLS is terminated at the ingress) | See Deploy an application and the image source type |
| Deploy rejected: raw secret | A spec contains a raw secret value | Use a secret reference, not a literal — see Rollback & deploy history |
When a recent deploy caused it
If the application was healthy before the last deploy, roll back to the previous good version while you investigate — diff-first, from the console, the CLI, or Nova:
astroctl app history myapp # find the last good version
astroctl app rollback myapp # preview the plan, then confirm
See Rollback & deploy history.