skip to content

An Aspire AppHost uses AddPostgres with WithDataVolume, and after a teammate clears user secrets PostgreSQL rejects the password: why, and how do you fix it?

level: seniorimportance: should knowfreq 27%

answer

  1. the volume remembers the first password
  2. generated parameter postgres-password
  3. saved to the AppHost's user secrets
  4. POSTGRES_PASSWORD applies only to an empty data directory
  5. aspire secret set Parameters:postgres-password

basics

~20 s

AddPostgres generates a postgres-password parameter that the run saves to the AppHost's user secrets. The data volume was initialized with that password, so clearing secrets makes Aspire generate and inject a new one the existing database rejects.

solid answer

~50 s

With no `password:` argument, `AddPostgres("postgres")` creates a secret parameter named `postgres-password` with a generated default of at least 22 characters. In run mode Aspire saves that generated value to the AppHost's user secrets under `Parameters:postgres-password`, so later runs reuse it. `WithDataVolume()` keeps PostgreSQL's data directory in a named volume, and the container image applies `POSTGRES_PASSWORD` only when it initializes an empty directory. Once the secret is cleared, Aspire generates a new password and injects it, but the cluster in the volume still has the old one: the health check fails, `WaitFor` keeps the API waiting and `AddDatabase` never creates its database. Fix it by restoring the old value with `aspire secret set Parameters:postgres-password <old>`, by deleting the volume if the data is disposable, or, durably, by declaring `AddParameter("postgres-password", secret: true)` and passing it as `password:`.

code

csharp · 13 lines
csharp
var builder = DistributedApplication.CreateBuilder(args);

var pgPassword = builder.AddParameter("postgres-password", secret: true);

var ordersDb = builder.AddPostgres("postgres", password: pgPassword)
    .WithDataVolume(name: "pizzashop-postgres-data")
    .AddDatabase("ordersdb");

builder.AddProject<Projects.PizzaShop_Api>("pizza-api")
    .WithReference(ordersDb)
    .WaitFor(ordersDb);

builder.Build().Run();

go deeper

for a junior

Recall that AddPostgres creates a postgres-password parameter when you give it none, and that WithDataVolume keeps the database files between runs.

for a middle

Explain why a data volume pins the first password and how the user-secrets entry Parameters:postgres-password keeps runs consistent.

for a senior

Diagnose the chain from failing health check to Waiting dependents, pick the least destructive fix, and move the team to an explicit secret parameter with a named volume.

for a principal

Decide how much local state a team should keep in volumes versus seeding fresh databases each run, weighing realism against reproducible onboarding.

## The setup A typical pizza-ordering AppHost keeps its local orders between runs: - `AddPostgres("postgres")` adds a PostgreSQL container resource. - `.WithDataVolume()` mounts a named volume at the image's data directory, so the database files survive when the session container is removed. - `.AddDatabase("ordersdb")` adds a child database resource the API references and waits for. It works for weeks. Then a teammate clears the AppHost's user secrets, or clones the repository into a fresh profile and copies an old volume, and PostgreSQL starts failing authentication while the API sits in the Waiting state. ## Where the password comes from `AddPostgres` takes an optional `password` parameter. When it is null, the integration calls `ParameterResourceBuilderExtensions.CreateDefaultPasswordParameter(builder, "postgres-password")`, which builds a **secret** parameter whose default is a generated value with a minimum length of 22 characters. In run mode that default is wrapped so that the first generated value is **written to the AppHost's user secrets** under `Parameters:postgres-password`. On the next run, configuration already holds that key, so the same password is used again. The write is best effort: without a `UserSecretsId` it silently fails and every run generates a new password. The aspire.dev page on volumes says the generated password changes on every run. The 13.6 source persists it to user secrets as described here, and when the two disagree the source is what runs. ## Why the volume rejects the new password The container receives the password as `POSTGRES_PASSWORD`. The PostgreSQL image uses that variable only while **initializing an empty data directory**. With a data volume, the directory is initialized on the first run and reused afterwards, so the role's password is whatever was set the first time. The failure sequence is: 1. User secrets are cleared, so `Parameters:postgres-password` is missing. 2. Aspire generates a fresh password, saves it, and injects it into the container and into every connection string. 3. PostgreSQL starts on the existing volume with the original password. 4. The integration's Npgsql health check fails, so the server never becomes Healthy. 5. The ready event that runs `CREATE DATABASE` for `ordersdb` never fires, and resources with `WaitFor(ordersDb)` stay Waiting. ## Fixes, from quickest to most durable | Fix | Effect | Cost | |---|---|---| | `aspire secret set Parameters:postgres-password <old value>` | config matches the volume again | you must know the old value | | delete the named volume | PostgreSQL re-initializes with the new password | local data is lost | | explicit `AddParameter("postgres-password", secret: true)` passed as `password:` | the team owns the value deliberately | each developer sets it once | The explicit parameter is the durable answer: the dashboard prompts for it when missing, the value is visible as a named parameter, and nobody is surprised by a generated secret. ## Related traps - **Volume names include a hash of the AppHost's path.** In 13.6 `WithDataVolume()` names the volume from the application name, the first ten characters of a SHA-256 of the AppHost path, the resource name and `data`. The docs show the shorter `{appHostProjectName}-{resourceName}-data` form. Moving or re-cloning the AppHost folder therefore yields a new, empty volume, which looks like lost data. Pass an explicit `name` to `WithDataVolume` when the volume must survive a move. - **Persistent containers widen the window.** `WithLifetime(ContainerLifetime.Persistent)` keeps the container itself between runs, so a stale container plus a changed password produces the same mismatch until the container is recreated. - **The database is created by Aspire, not by the image.** `AddDatabase` runs `CREATE DATABASE` once the server is ready, so an authentication failure also means `ordersdb` never appears. ## Confirming the diagnosis Before deleting anything, confirm the cause: 1. In the dashboard, the `postgres` resource is Running but not Healthy, and the API shows Waiting. 2. The PostgreSQL console log shows password authentication failures for the configured user. 3. `aspire secret list` shows whether `Parameters:postgres-password` exists in the AppHost's user secrets. 4. The container runtime still lists the old named volume, so the cluster on disk predates the current password. If all four hold, the problem is a password mismatch, not a broken image or a networking fault, and restoring the old secret is the cheapest repair.

  • How would you find the volume an existing AppHost uses if no name was given?
    List the container runtime's volumes and look for one ending in `-postgres-data`; in 13.6 the generated name is the application name, a ten-character hash of the AppHost path, the resource name and `data`.
  • Does the same trap exist for Redis or SQL Server resources?
    Yes for any integration that generates a password parameter and keeps state in a volume. `AddRedis` and `AddSqlServer` also create `{name}-password` parameters, so clearing user secrets while keeping their data volumes produces the same mismatch.

  • PostgreSQL re-applies POSTGRES_PASSWORD to an existing data directory on every start.
  • Clearing user secrets cannot affect containers, because Aspire generates nothing at run time.
  • WithDataVolume persists the container, so the old password container is simply reused.
  • The only fix is to delete the volume and lose the local data.
  • AddDatabase failed because the image creates ordersdb, not Aspire.

Assumes Aspire 13.6 source, which saves a generated password to the AppHost's user secrets in run mode; the aspire.dev volume page still says the generated password changes every run.