Starter docs

Troubleshooting

The database or the broker never becomes healthy

Symptom: the dashboard waits forever on postgres or rabbitmq, and their logs say password authentication failed or invalid credentials.

Cause: the AppHost runs PostgreSQL, RabbitMQ, Redis and MailPit as persistent containers, kept between runs on named volumes. A database takes its password from the volume it was created on, not from Parameters:sql-password. A volume created before the secrets were set — or before sql-password changed — keeps the old password, and Aspire's health check retries it without saying why.

Fix: set the old password back in the user secrets, or start from nothing. This deletes the development data; the seed writes the sample data back:

# The AppHost's persistent containers, then their volumes
docker rm -f $(docker ps -aq --filter label=com.microsoft.developer.usvc-dev.persistent=true)
docker volume rm $(docker volume ls -q --filter name=blouppy.aspire.apphost)
docker volume rm mailpit-data   # the caught e-mails, if you want them gone too

HTTPS certificate errors

Symptoms:The remote certificate is invalid because of errors in the certificate chain: UntrustedRoot, the gateway answering 502, or Angular serving a certificate that is not the trusted one.

Cause: more than one development certificate is in play. The Angular apps export the ASP.NET Core certificate to PEM files (aspnetcore-https.js); if those files come from an older certificate, the services do not trust each other.

Fix: reduce it to one certificate.

  1. Delete the exported files: blouppy.pem and blouppy.key in ~/.aspnet/https/ (macOS, Linux) or %APPDATA%\ASP.NET\https\ (Windows).

  2. Reset the certificate:

    dotnet dev-certs https --clean
dotnet dev-certs https --trust
dotnet dev-certs https --check   # exactly one valid certificate

  3. On Linux, check that SSL_CERT_DIR includes ~/.aspnet/dev-certs/trust (see Prerequisites).

  4. Start the AppHost again.

A port is already in use

Something else holds 5071, 59808, 8025… — often the containers of an earlier run; docker ps names them. The end-to-end suite uses the same ports with containers of its own, so stop the development containers before running it.

toomanyrequests while pulling an image

Docker Hub's anonymous limit. Run docker login, or configure a registry mirror (see Prerequisites).

npm ci reports an entry missing from the lock file

Your npm is older than the one that wrote the lockfile: npm install --global npm@12.