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

Overview

error: constructing secrets manager of type "passphrase": passphrase must be set with PULUMI_CONFIG_PASSPHRASE or PULUMI_CONFIG_PASSPHRASE_FILE environment variables means your stack uses the passphrase secrets provider, but Pulumi cannot find the passphrase it needs to encrypt and decrypt secret config values. Without it, Pulumi cannot construct the secrets manager and refuses to proceed.

This provider is the default when you use a self-managed backend (local filesystem, S3, Azure Blob, GCS) rather than Pulumi Cloud. The passphrase is chosen at stack creation and must be supplied on every command that touches secrets. It is most commonly seen in CI, where interactive prompts are disabled and the env var was never set.

error: constructing secrets manager of type "passphrase": passphrase must be set with PULUMI_CONFIG_PASSPHRASE or PULUMI_CONFIG_PASSPHRASE_FILE environment variables

Symptoms

• pulumi up, pulumi preview, pulumi stack select, or pulumi config fails with the passphrase must be set message.
• The failure happens in CI/CD or scripts but not interactively (locally Pulumi prompts you for the passphrase).
• The stack’s Pulumi.<stack>.yaml contains an encryptionsalt: line, confirming the passphrase provider.
• pulumi config set --secret refuses to store a value.

Common Root Causes

1. Env var not exported in CI

Interactive sessions prompt for the passphrase, but non-interactive runs cannot. If the pipeline never exports PULUMI_CONFIG_PASSPHRASE, construction of the secrets manager fails.

PULUMI_CONFIG_PASSPHRASE unset in the job environment

2. Stack was initialized with the passphrase provider

Self-managed backends default to passphrase. Any secret in config (or the salt itself) requires the passphrase on every operation.

grep encryptionsalt Pulumi.dev.yaml

3. Variable set in the wrong shell/scope

Exporting the passphrase in one shell or step does not carry into a separate step, sub-shell, or container that runs the actual pulumi command.

4. Empty passphrase not signalled correctly

If the stack was created with an intentionally empty passphrase, you must still export the variable as empty (PULUMI_CONFIG_PASSPHRASE=""); leaving it entirely unset triggers the error.

5. Using a passphrase file that is missing

PULUMI_CONFIG_PASSPHRASE_FILE points at a file that does not exist or is unreadable in the runner.

How to Diagnose

Confirm the stack uses the passphrase provider (look for encryptionsalt, not secretsprovider: ...cloud...):

cat Pulumi.dev.yaml

Check whether the env var is actually present in the current environment:

printenv PULUMI_CONFIG_PASSPHRASE

See which backend you are logged into (self-managed backends default to passphrase):

pulumi whoami --verbose

Try a read-only config command — it fails the same way if the passphrase is missing:

pulumi config

Fixes

Export the passphrase before running Pulumi: Set the environment variable in the same shell/step that invokes pulumi.

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

Use a passphrase file: Store the passphrase in a file and point Pulumi at it — handy when a secret manager mounts it to disk.

export PULUMI_CONFIG_PASSPHRASE_FILE=/run/secrets/pulumi_passphrase
pulumi up --stack dev

Inject it from your CI secret store: In GitHub Actions, GitLab CI, etc., add the passphrase as a masked secret and export it for the job.

# GitHub Actions example (job env)
#   env:
#     PULUMI_CONFIG_PASSPHRASE: ${{ secrets.PULUMI_CONFIG_PASSPHRASE }}
pulumi preview --stack prod

Set an empty passphrase explicitly if that is how the stack was created: Unset is an error; empty is valid.

export PULUMI_CONFIG_PASSPHRASE=""
pulumi stack select dev

Switch to a cloud KMS secrets provider (longer-term): To avoid managing a passphrase, migrate the stack to a KMS-backed provider so no env var is needed.

pulumi stack change-secrets-provider "awskms://alias/pulumi?region=us-east-1"

Rotate/recover a lost passphrase: If nobody knows the passphrase, you cannot decrypt existing secrets — you must reset them. Re-init the secrets or set a new provider, then re-enter each secret value.

pulumi stack change-secrets-provider passphrase

What to Watch Out For

• The passphrase decrypts your secrets — if it is lost, encrypted config values are unrecoverable. Store it in a real secret manager.
• Set the variable in the same job step that runs pulumi; exporting it in an earlier, separate step usually does not persist.
• An empty passphrase must be exported as ""; leaving it unset is treated as missing.
• PULUMI_CONFIG_PASSPHRASE_FILE takes precedence patterns vary — do not set both to conflicting values.
• Pulumi Cloud-backed stacks use a service-managed secrets provider and do not need this variable; the error signals a self-managed/passphrase stack.
• Never echo the passphrase into build logs; use masked CI variables.

Related Guides

• Pulumi Error: ‘failed to decrypt configuration’ — Troubleshooting Guide
• Pulumi Error: ‘PULUMI_ACCESS_TOKEN must be set’ — Troubleshooting Guide
• Pulumi Error: ‘Missing required configuration variable’ — Troubleshooting Guide