# Self-hosted troubleshooting

> Exit codes and the errors seen during real installs, with the fix for each.

Source: https://diakrin.com/docs/self-hosted/troubleshooting

Every command is safe to run again, and every error names its fix in `error.nextAction`, so start by running the same command a second time.

## Before you start

| You supply | Example | Comes from |
| --- | --- | --- |
| The command that failed | `diakrin self-hosted deploy --env diakrin.env` | Your terminal |
| The exit code | `7` | `echo $?` right after the command |

Find where an installation stands:

```sh
diakrin self-hosted status --env diakrin.env
```

You should see a phase (`infrastructure-incomplete`, `awaiting-dns`, `infrastructure-ready` or `deployed`) and the next command to run.

## Exit codes

| Exit | Meaning | Do this |
| --- | --- | --- |
| 0 | Done | Nothing |
| 1 | It ran and failed, or `doctor` found a problem | Read `error.nextAction` and run the same command again |
| 2 | Invalid input or a missing precondition | Fix `diakrin.env` or the flag named in the message |
| 3 | AWS credentials are missing or expired | Sign in again (`aws sso login`), then rerun |
| 4 | AWS denied a call | Grant the permission named in the message |
| 5 | Conflict with what is installed | Do what `nextAction` says. Never force through a mismatch |
| 6 | Network, throttling or timeout | Run the same command again |
| 7 | Waiting on a DNS record | Add the record, then run the same command again |

## Install

| You see | It means | Do this |
| --- | --- | --- |
| `awaiting-dns` (exit 7) | A certificate record is missing at the DNS provider | Run `diakrin self-hosted dns --env diakrin.env`, add what it lists, then run `infra up` again |
| `ACCOUNT_MISMATCH` (exit 5) | The AWS session is in another account than `DIAKRIN_ACCOUNT_ID` | Sign in to the right account |
| `REGISTRY_AUTH` (exit 3) | The image registry refused a token | Check network access to the registry, then rerun `deploy` |
| `IMAGE_COPY` (exit 6) | A network error while copying images | Run `deploy` again; copied layers are skipped |
| `IAM_NOT_READY` or "ECS was unable to assume the role" | A new IAM role has not propagated yet | Wait two minutes and run the same command again |
| `TASK_FAILED` | A one-off task such as migrations failed | Read the log lines in the message |
| `CLI_TOO_OLD` or `RELEASE_TOO_OLD` | The release needs a newer CLI | Run the install command again to update the CLI |
| `TERRAFORM_STATE_UNSAVED` | The state was not saved after a network error | Run the same `infra up` command again; do not edit state by hand |

## After deploy

| You see | It means | Do this |
| --- | --- | --- |
| `doctor` reports `Console from the internet` failing | The host record is missing, or CloudFront cannot reach the load balancer | Run `diakrin self-hosted dns`, then `diakrin self-hosted status` |
| `https://<host>/setup` shows "not found" | The request did not ask for HTML | Open it in a browser, not with `curl` |
| `doctor` warns that GitHub source ranges changed | GitHub published new ranges | Run `diakrin self-hosted doctor --fix` |
| Webhook returns HTTP 403 from outside GitHub | The firewall blocked it, which is correct | Send the webhook from GitHub only |
| `rollback` leaves the API restarting | You rolled back with CLI older than 0.1.7 | Update the CLI, then run `rollback` again |

## Remove

| You see | It means | Do this |
| --- | --- | --- |
| `DESTROY_INCOMPLETE` (exit 1) | Part of the removal failed; the records are kept | Run the same `destroy` command again |
| Resources still listed by the AWS tag search | The tag index lags behind deletions | Check each service; the CLI does this for you |

> [!SELF-HOSTED]
> Never share plan output, state files or tokens with anyone, including Diakrin support. Send support the command and the message it printed.

## Next

Return to [Operate your installation](/docs/self-hosted/operate).
