Self-hosted (AWS)
Self-hosted troubleshooting
Exit codes and the errors seen during real installs, with the fix for each.
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:
diakrin self-hosted status --env diakrin.envYou 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 |
Next
Return to Operate your installation.