Diagnose problems

Find out why an alis command failed and fix it: read the diagnostics snapshot, interpret the exit code, and apply the known fix for the common errors.

Prerequisites

• The CLI installed.

Steps

1. Take the diagnostics snapshot:

   ❯ alis doctor
   

   It shows the CLI, IDE extension and agent plugin versions against the detection cache, your auth state and active account, setup steps installed, settings and the recent log tail. Credentials are never included. alis doctor --json gives the same as an object; --no-logs drops the log tail.

2. Read the exit code of the failing command and act on it:

   Exit	Meaning	Fix
   1	Usage error or a failed operation.	Read the structured failure on stdout (under --json), then the operation's logsUri or alis logs build|deploy <name> --json.
   3	Confirmation required.	Re-run the envelope's retry after a human approves. Production needs --confirm-production; other gated commands need --approve.
   4	Signed out.	alis login, then retry.
   5	Nothing changed before a wait's --timeout.	Not a failure; wait again.

3. Match the error code in the envelope to its fix:

   Code	Fix
   TTY_REQUIRED	You ran bare alis without a terminal. Use subcommands with --json.
   LOGIN_CODE_REQUIRED	Bare alis login in a headless call. Use alis login --json, then alis login <code> --json.
   ACTIVE_BUILD_ACCOUNT_REQUIRED	alis accounts list --json, choose, alis accounts select accounts/<id> --json.
   ENVIRONMENT_SELECTION_REQUIRED	Pass -e <env-id>; ids in details or alis context view --json.
   ENV_NOT_FOUND	Write the product's .env: alis environment refresh <org>.<product>.<env> --output <product>/.alis/.env.
   TIMEOUT	A headless command hit a prompt nobody answered. Run retry once; if it repeats, alis doctor --json has the command log.
   NETWORK_UNAVAILABLE, network_unreachable	This machine cannot reach the platform (DNS, sandbox, proxy). Retry once with network access; do not infer an outage.
   backend_outdated	The backend predates this feature. Retry later.
   not_organisation_admin	Use alis product request instead of alis product new.
   CONFIG_REQUIRED, INVALID_CONFIG	A dedicated-service block needs a valid --config; the schema is in alis skills load block-<id>.

4. Fix the common local problems:

   Symptom	Fix
   command not found: alis after installing	~/.alis/bin/alis setup path, then open a new terminal.
   Git prompts for a password, or fails with a stale http.extraHeader	alis authorise <org>.<product> --json once (alias alis a).
   Go: unrecognized import path "alis.build/...", or a TLS error fetching a private package	alis packages install <pkg> --language go --json. A fresh clone always needs it once. Do not copy GOPROXY settings from a Dockerfile.
   Install fails with "no published definition yet"	alis define <pkg> first, then retry.
   Generated types look stale after a define	alis packages install <pkg>; for every alis.build dependency, alis packages upgrade <pkg>.
   Another product's package is missing or stale	An admin of the owning product runs alis packages share <that-pkg> --with <your-org.product> --json.
   An old alis keeps running after an upgrade	Remove the older copy earlier on your PATH, or alis setup path.
   Workstation: "this workstation is locked to build environment …"	Expected; alis workstation open <org> opens the other organisation's workstations.

5. Still stuck? Send the snapshot to your build specialist with a short, factual message:

   Shell

   alis specialist send-message --message "<subject line>\n\n<problem, impact, evidence, help needed>" --json
   alis doctor --ticket <ticket-id>
   

Related: Exit codes, alis doctor, Raise and read support tickets.