12. If something goes wrong

First, find the reason: CloudFormation → your stack → Events tab → type FAILED in the search box → read the Status reason of the earliest red line.

What you see

Cause

What to do

not authorized to perform: iam:GetRole (or iam:CreateRole, iam:PassRole)

Your AWS sign-in lacks IAM permissions

Use an administrator sign-in, or add Appendix A. Delete the failed stack and create it again.

RunMigrations failed — “…migrate-control failed (exit 1…). Last output: …”

Database preparation failed

The text after Last output: is the end of the database log and names the problem. Copy the whole status reason and send it to support. (On a first install the rollback deletes the log group itself, so this reason is the copy that remains.)

FIRST_ADMIN_USERNAME must be 3-15 characters… in the migrations log

Invalid first-admin value

Fix the field (Step 9, Section 4) and update the stack.

A service never becomes stable; the stopped-task reason mentions pulling the image (CannotPullContainerError)

Private subnets cannot reach the internet

Add a NAT gateway to the private subnets (checklist, section 2).

A new stack, or an update to InternalTlsMode = required, fails — RunMigrations: “…the admin-api certificate has not been installed”

ImageTag names a release older than the one that creates the certificates itself

New stack: delete it and create it again with the ImageTag given in Step 1. Update: the stack rolled back; update again with that ImageTag.

The sign-in page loads, but signing in or every page shows an error (502)

The VPC has DNS hostnames or DNS resolution turned off, so the services cannot find each other

Turn both on (checklist, section 2), then ECS → your cluster → each service → Update → Force new deployment.

Website shows a certificate warning

The certificate does not name your domain, or DNS is not set up yet

Check Step 2 and Step 13.

Sign-in provider says redirect_mismatch / redirect_uri_mismatch

The return address is not registered with the provider

Register the exact address from section 10.

Sign-in says Origin not allowed by CORS, or pages load but saving anything fails

PublicBaseUrl is empty or different from the address in the browser

Set PublicBaseUrl to exactly https://<your domain> and update the stack.

New users never receive their password email

Mail is not configured

Admin → System → Mail (section 9).

Deleting the stack ends in DELETE_FAILED — “Cannot create a snapshot because the database instance … is not currently in the available state”

The stack was deleted while the database was still being created; before deleting it the stack keeps a final snapshot, which needs the database to be Available

RDS → Databases: wait until the database shows Available, then CloudFormation → your stack → Delete again. Everything else was already removed.