anomalyco/sst · error · VisibleError

You must provide the password to connect to your locally run

Error message

You must provide the password to connect to your locally running database either by setting the "dev.password" or by setting the top-level "password" property.

What it means

In `sst dev`, the Aurora component runs the database locally (e.g. via Docker) and needs a password to initialize/connect to it. In dev mode, SST does not use the AWS-managed secret, so you must provide the password explicitly via `dev.password` on the component or the top-level `password` argument.

Source

Thrown at platform/src/components/aws/aurora.ts:841

        return {
          subnets: args.vpc.privateSubnets,
          securityGroups: args.vpc.securityGroups,
        };
      }

      // "vpc" is object
      return output(args.vpc);
    }

    function registerDev() {
      if (!args.dev) return undefined;

      if (
        $dev &&
        args.dev.password === undefined &&
        args.password === undefined
      ) {
        throw new VisibleError(
          `You must provide the password to connect to your locally running database either by setting the "dev.password" or by setting the top-level "password" property.`,
        );
      }

      const dev = {
        enabled: $dev,
        host: output(args.dev.host ?? "localhost"),
        port: all([args.dev.port, engine]).apply(
          ([port, engine]) => port ?? { postgres: 5432, mysql: 3306 }[engine],
        ),
        username: args.dev.username ? output(args.dev.username) : username,
        password: output(args.dev.password ?? args.password ?? ""),
        database: args.dev.database ? output(args.dev.database) : dbName,
      };

      new DevCommand(`${name}Dev`, {
        dev: {
          title: name,

View on GitHub (pinned to a0bd20f762)

Solutions

1. Add `dev: { password: "..." }` to the Aurora component args in sst.config.ts
2. Or set the top-level `password` argument on the component, which is used in dev when `dev.password` is absent
3. Use a secret-safe value (e.g. from `sst.Secret` or a dev-only literal) and ensure it matches the password the local container is initialized with

Example fix

// before
new sst.aws.AuroraPostgres("DB", {});
// after
new sst.aws.AuroraPostgres("DB", {
  dev: { password: "my-local-dev-password" }
});

if ($dev && args.dev?.password === undefined && args.password === undefined)
  throw new Error('Set dev.password (or top-level password) on the Aurora component for sst dev');

function hasDevPassword(args, $dev) {
  return !$dev || args.dev?.password !== undefined || args.password !== undefined;
}

try {
  const db = new sst.aws.AuroraPostgres("DB", args);
} catch (e) {
  if (String(e).includes("provide the password")) {
    throw new Error('Add dev: { password: "..." } to the Aurora component before running sst dev');
  }
  throw e;
}

When it happens

Trigger: Running `sst dev` with an Aurora/AuroraPostgres component where neither `dev.password` nor the top-level `password` argument is set (`$dev` is true and both are undefined).

Common situations: Running local dev for the first time on a config written for deploy-only; a teammate's sst.config.ts relying on credentials stored elsewhere; CI/devcontainers where env-provided passwords aren't wired into the config.

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

• You must provide the password to connect to your locally run
• You must provide the password to connect to your locally run
• Database instance not found in cluster ${cluster.id}
• Failed to get password for Postgres ${name}.
• Cannot configure "pauseAfter" when the minimum ACU is not 0

AI-assisted analysis of anomalyco/sst@a0bd20f762 (2026-08-30). Data as JSON: /api/errors/fb7569c651561be8. Report an issue: GitHub.