Debug a deployment
Debugging a deployment means finding out why it failed, stalled, or returns errors, without access to the customer's account. It starts with read-only commands:
alien deployments get customer-1/us-east-1
alien deployments events customer-1/us-east-1 --limit 50
alien logs --deployment customer-1/us-east-1 --level error --since 1hGo further down only when the step above doesn't answer your question. The first steps read what the deployment already reported. A debug session needs someone else's approval.
If you already know the symptom, Troubleshooting goes straight to the fix.
| Step | Command | Answers |
|---|---|---|
| Status | alien deployments get | What state is it in, which release, what failed first, who acts? |
| Events | alien deployments events | What changed, when, and who started it? |
| Logs | alien logs | What did your code and the platform print? |
| Inventory | alien deployments resources, machines | Which resource or host is unhealthy? |
| Commands | alien commands invoke | What does your app report about its own state? |
| Debug session | alien debug | What does the cloud or cluster say? Needs an approved access request. |
| Host shell | alien debug exec | What's happening on the host? Your machines and Local only. |
A deployment is a dep_… ID or <group>/<name>. Pass --project when the directory isn't linked to the project, and --workspace when you're signed in to several.
Read the status
alien deployments get (also alien status <deployment>) prints the deployment's last report:
alien deployments get customer-2/mainShowing deployment main
ID dep_4f8n2c
Status update-failed
Platform kubernetes
Current release rel_6w1pz3
Desired release rel_7x2kq9
Deployment failed: 1 resource error(s), 1 interrupted, 4 total
Failed resources:
- api: Managed workload 'api' failed (CrashLoopBackOff): back-off restarting failed containerRead it top to bottom:
- Status. Where the deployment is in its lifecycle. See Statuses.
- Current release and Desired release. When they differ, the deployment hasn't applied its target release yet.
- Failed resources. The resources that failed on their own. Fix these.
- Deployment updates. One row per update operation, with Status, Target release, Reasons, and Action required. Action required names a step outside Alien, such as
Apply the updated setup to continue this update. - Resources. Every resource with its status and details.
Add --json for the full record, including each resource's error and the update operations.
First failure, not interrupted
When one resource fails, Alien stops the resources that were waiting on it and marks them interrupted, with Resource was not deployed because resource 'api' failed. The summary line counts them separately: 1 resource error(s), 1 interrupted.
Fix the resource under Failed resources. The interrupted ones deploy on the next retry.
Wrapper errors
Some errors only say that a resource stopped making progress: Polling timed out after N attempts in state '…', a failed health check, or CrashLoopBackOff. They don't say why. The cause is in the logs, usually the first error after the replica started.
Read the events
alien deployments events customer-1/us-east-1 --limit 50Events show when an update started, which release it targeted, and whether a health check keeps flapping. Each row has Time, State, Actor, Event, and Details. --limit takes up to 100.
Actor is the member's email, a service account for an API key, or System for changes Alien made on its own.
Search the logs
# Errors from your code in the last hour
alien logs --deployment customer-1/us-east-1 --level error
# Platform logs: image pulls, mounts, credentials, the machine agent
alien logs --deployment customer-1/us-east-1 --system --level error --since 2h
# The minute a customer reported
alien logs --deployment customer-1/us-east-1 \
--from 2026-01-15T09:00:00Z --to 2026-01-15T09:02:00Z -q '429'--systemadds logs from Alien's own components. Errors that never reach your code appear only here, such as an image that can't be pulled or a role that can't be assumed.--fromand--totake RFC 3339 timestamps with a zone.--sincetakes a duration such as30mor7d. The default window is the last hour.-qsearches text, for example-q '"rate limit exceeded"'or-q 'timeout OR refused'.--limitdefaults to 200 and allows up to 1000 records per query. For more, split the time window into several queries.--jsonprints records for scripts.--followkeeps polling for new ones.
See Logs and metrics for the search syntax and log forwarding.
Check resources and machines
alien deployments resources customer-1/us-east-1
alien deployments machines customer-1/us-east-1resources lists each resource with Status, Machines (current and desired count for a compute cluster), and Details, without configuration or secrets.
machines lists the hosts connected to the deployment, with Status, Heartbeat, Network, Peers, and Machine agent version. When the deployment shows Not reporting but its machines have fresh heartbeats, the hosts are up and the problem is in reporting, not an outage.
Ask your app
alien commands invoke --deployment customer-1/us-east-1 \
--command queue-depth --params '{"queue":"exports"}'A command runs a handler you wrote inside the deployment and returns only what it chooses to. Use it to read application state, such as queue depth or a job's progress. No approval is needed.
Open a debug session
alien debug customer-1/us-east-1 --request-access -- aws sts get-caller-identityalien debug runs aws, gcloud, az, or kubectl on your machine with credentials scoped to one deployment.
On AWS, Google Cloud, Azure, and Remote Operator deployments, it needs an approved access request: time-boxed permission that someone other than you approves. That's the customer on Kubernetes and a teammate elsewhere.
--request-accesscreates one and waits for approval.- Without one, Alien refuses with
DEBUG_ACCESS_REQUEST_REQUIRED. Don't look for credentials another way.
On a push deployment, the session runs as the management identity, the cloud role Alien uses for ongoing management. It can do what the initial setup granted that role and nothing more. See Debug sessions.
Run a command on the host
alien debug exec customer-1/edge-site --machine m_2k7d -- journalctl -u my-daemon --since "10 min ago"
alien debug exec customer-1/edge-site --resource api -- cat /etc/os-release
alien debug shell customer-1/edge-sitedebug exec and debug shell run inside the runtime of a Your machines or Local deployment. --machine targets a host and --resource a Container or Daemon. exec times out after 120 seconds (--timeout-seconds).
On AWS, Google Cloud, Azure, and Kubernetes they return FEATURE_NOT_SUPPORTED. Use a command or a debug session there.
By symptom
| You see | Start with | Usual next step |
|---|---|---|
| A failed status | Failed resources in get | Logs for that resource, fix, alien deployments retry |
| Running, but current and desired release differ | Deployment updates in get | Follow Action required. See Held release. |
| Stuck in Pending, Updating, or Initial setup | events, then logs --system | Look for an error that repeats. See Stuck. |
| Running, but users see errors | logs for the reported time window | logs --system to rule out the platform, then commands invoke |
| Not reporting | machines, then resources | logs --system. See Not reporting. |
| No logs | The telemetry setting | See Logs are missing. |
| Teardown required | get | The admin deletes what initial setup created. See Teardown required. |
| A CLI error | The message | See CLI errors. |