🚨 Pulumi Error: 'getting secrets manager: passphrase must be set with PULUMI_CONFIG_PASSPHRASE' — Cause, Fix, and Troubleshooting Guide

Overview

error: getting secrets manager: passphrase must be set with PULUMI_CONFIG_PASSPHRASE fires when Pulumi tries to initialize the stack’s secrets manager and the passphrase provider has no passphrase to work with. This happens at a different point than a decryption failure: here Pulumi cannot even construct the secrets manager because the required input — the passphrase env var or file — is absent or empty. It shows up on almost any stack operation, because Pulumi loads the secrets manager early, even to read non-secret config.

The message is explicit about what it needs:

error: getting secrets manager: passphrase must be set with PULUMI_CONFIG_PASSPHRASE or PULUMI_CONFIG_PASSPHRASE_FILE environment variables

The stack’s secretsprovider is passphrase (the default for self-managed/local and DIY backends), and Pulumi found neither PULUMI_CONFIG_PASSPHRASE nor PULUMI_CONFIG_PASSPHRASE_FILE in the environment. Unlike failed to decrypt configuration value (wrong key for existing ciphertext), this error is about the passphrase being missing entirely — even a stack with no secrets yet can hit it because the manager still needs to initialize.

Symptoms

• Nearly every command (pulumi up, preview, config, stack select) fails with getting secrets manager: passphrase must be set ....
• The stack uses the passphrase secrets provider (typical with pulumi login --local, s3://, gs://, azblob://, or file:// backends).
• Occurs in CI where the passphrase secret was never injected, or on a fresh machine.
• Happens on a brand-new stack that has no secrets yet — initialization still requires the passphrase.
• echo $PULUMI_CONFIG_PASSPHRASE prints nothing.

Common Root Causes

1. Passphrase env var not set at all

The most common case: PULUMI_CONFIG_PASSPHRASE (and _FILE) are simply unset in the current shell or CI job.

echo "${PULUMI_CONFIG_PASSPHRASE:-<unset>}"
# <unset>

2. Passphrase not injected into CI

The pipeline runs Pulumi but the passphrase secret was never mapped into the job’s environment.

error: getting secrets manager: passphrase must be set with PULUMI_CONFIG_PASSPHRASE ...

3. Passphrase file path wrong or unreadable

PULUMI_CONFIG_PASSPHRASE_FILE points at a path that does not exist or the process cannot read.

4. Empty passphrase not allowed by default

An exported-but-empty PULUMI_CONFIG_PASSPHRASE="" is treated as unset. To intentionally use an empty passphrase you must opt in with PULUMI_CONFIG_PASSPHRASE_FILE pointing at an empty file, or set the experimental empty-passphrase flag.

5. Stack expects a cloud provider but resolves passphrase

The stack was meant to use KMS/Pulumi Cloud, but its secretsprovider is (still) passphrase, so Pulumi demands a passphrase you never intended to supply.

How to Diagnose

Confirm the stack’s secrets provider — this must say passphrase for this error to be relevant:

grep secretsprovider Pulumi.dev.yaml

Check whether either passphrase variable is present:

env | grep -i PULUMI_CONFIG_PASSPHRASE

If using a file, confirm it exists and is readable:

ls -l "$PULUMI_CONFIG_PASSPHRASE_FILE"
cat "$PULUMI_CONFIG_PASSPHRASE_FILE"

In CI, print (masked) whether the secret is wired without echoing its value:

if [ -z "${PULUMI_CONFIG_PASSPHRASE:-}" ]; then echo "passphrase MISSING"; else echo "passphrase present"; fi

Fixes

Cause 1 & 2 — set the passphrase. Export it in the shell or inject it as a CI secret:

export PULUMI_CONFIG_PASSPHRASE='your-stack-passphrase'
pulumi up

In GitHub Actions, map the repository/organization secret into the step env:

# workflow step
env:
  PULUMI_CONFIG_PASSPHRASE: ${{ secrets.PULUMI_CONFIG_PASSPHRASE }}

Cause 3 — file path: Point the file variable at a real, readable file containing only the passphrase:

export PULUMI_CONFIG_PASSPHRASE_FILE=/run/secrets/pulumi-passphrase
pulumi up

Cause 4 — intentional empty passphrase: Use an empty file rather than an empty string:

touch /tmp/empty-passphrase
export PULUMI_CONFIG_PASSPHRASE_FILE=/tmp/empty-passphrase
pulumi up

Cause 5 — you wanted a cloud provider: Migrate the stack off passphrase to KMS or Pulumi Cloud so no passphrase is required. This re-encrypts existing secrets:

pulumi stack change-secrets-provider "awskms://alias/pulumi-dev?region=us-east-1"
# or, to use the Pulumi Cloud service:
pulumi stack change-secrets-provider service

What to Watch Out For

• This error is about a missing passphrase at init time; failed to decrypt configuration value is about a wrong passphrase for existing ciphertext. Fixes differ — check which message you actually have.
• Even stacks with zero secrets need the passphrase, because Pulumi initializes the secrets manager on load.
• An empty string is not an empty passphrase — use PULUMI_CONFIG_PASSPHRASE_FILE with an empty file if you truly want none.
• In CI, wire the passphrase as a masked secret and add a pre-flight check that fails fast with a clear message if it is missing.
• For teams, prefer KMS or Pulumi Cloud secrets providers so decryption is tied to IAM rather than a shared string that everyone must have exported.
• Never commit the passphrase to the repo; committing the encrypted Pulumi.<stack>.yaml is fine, the passphrase is not.

Related Guides

• Managing Secrets in Infrastructure as Code
• Pulumi Error: ‘conflict: another update is in progress’ — Troubleshooting Guide
• GitOps for Infrastructure Explained