Troubleshoot a Deployment
When an application is not behaving, the platform gives you the same diagnostic surfaces 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.
Every command below has a matching tab in the application's console detail view (Overview, Events, Logs), and you can ask Nova in plain language — for example "why is myapp failing?" Nova reads the same status, events, and logs and summarizes the likely cause.
1. Check status
Start with the current state — 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
In the console, this is the application's Overview tab.
2. Read the events
Events explain why a rollout is stuck. There are 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 -w to stream events as they happen. In the console, both are under the Events tab.
3. Read the logs
astroctl app logs myapp # follows by default (Ctrl-C to stop)
Logs cover all pods for the application. In the console, use the Logs tab.
4. Force a re-sync
If the desired spec is correct but the cluster has drifted or a sync is stuck, trigger a re-sync:
astroctl app resync myapp
In the console, this is the Force Sync button on the application.
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.
With Nova
Ask "why is myapp unhealthy?" or "show me the errors in myapp's logs." Nova reads the application's 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.