---
title: "Diagnose problems"
url: "https://docs.alisx.com/how-to/cli/diagnose-problems/"
---
# 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:

    ```bash title="Terminal"
    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:

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

Related: [Exit codes](https://docs.alisx.com/reference/cli/exit-codes.md), [alis doctor](https://docs.alisx.com/reference/cli/doctor.md), [Raise and read support tickets](https://docs.alisx.com/how-to/help/raise-and-read-support-tickets.md).