🚨 Pulumi Error: 'invalid configuration key: dbPassword. A configuration key must be of the form namespace:name' — Cause, Fix, and Troubleshooting Guide

Overview

error: invalid configuration key means you tried to set or read a Pulumi config value whose key is not in the required <namespace>:<name> form. Every Pulumi config key belongs to a namespace — usually your project name, or a provider like aws. When you pass a bare key such as dbPassword, Pulumi cannot tell which namespace it belongs to and rejects it.

error: invalid configuration key: 'dbPassword'. A configuration key must be of the form '<namespace>:<name>'

The confusing part is that inside your program you read config with just config.require("dbPassword") — no namespace. That works because pulumi.Config() defaults the namespace to your project name. On the command line, though, an unqualified key is only auto-namespaced in specific cases, and structured/edge cases force you to be explicit.

Symptoms

• pulumi config set dbPassword ... (or a similar command) fails immediately with invalid configuration key.
• The message insists on the form <namespace>:<name>.
• It happens with pulumi config set, pulumi config get, pulumi config rm, or a --config/--secret flag on pulumi up.
• Reading the value inside Python previously worked, so the key “looks” valid to you.
• You copied a command from docs or a script that assumed a different project name.

Common Root Causes

1. Missing project namespace prefix

Pulumi config keys are namespaced. A key you think of as dbPassword is really <project>:dbPassword, where <project> is the name: field in Pulumi.yaml. Some commands and contexts refuse to guess.

# rejected
pulumi config set dbPassword s3cr3t

# accepted (project named "my-infra")
pulumi config set my-infra:dbPassword s3cr3t

2. Setting provider config without its namespace

Provider settings live under the provider’s own namespace, most commonly aws:. Writing region instead of aws:region is invalid.

# wrong
pulumi config set region us-east-1

# right
pulumi config set aws:region us-east-1

3. Using --path structured keys that need a namespace

When you set nested/structured config with --path, the top-level key still needs its namespace, and mis-quoting the path can also produce an invalid key.

# structured key still namespaced
pulumi config set --path 'my-infra:data.retentionDays' 30

4. Wrong project name assumption

If you copied a command that used a different project’s name (e.g. demo:key) into a project named my-infra, the key is technically valid form but wrong namespace — and a bare key from such a script trips the error.

How to Diagnose

Find your project’s namespace (the name: in Pulumi.yaml):

grep '^name:' Pulumi.yaml

List the keys already set for the current stack — they show the correct namespaced form:

pulumi config

Show a single value with its full key to confirm the namespace you should use:

pulumi config get my-infra:dbPassword

Fixes

Prefix the key with your project name: Take the name: value from Pulumi.yaml and put it before a colon.

# Pulumi.yaml has: name: my-infra
pulumi config set my-infra:dbPassword s3cr3t

# store secrets encrypted with --secret
pulumi config set --secret my-infra:dbPassword s3cr3t

Use the provider namespace for provider settings: Provider keys use the plugin’s namespace, not your project’s.

pulumi config set aws:region us-east-1
pulumi config set aws:profile my-sso-profile

Read it in Python with the short name: Inside the program, pulumi.Config() is already scoped to your project namespace, so you use the unqualified name.

import pulumi

config = pulumi.Config()               # namespace = project name
db_password = config.require_secret("dbPassword")

# For a provider or another namespace, name it explicitly:
aws_config = pulumi.Config("aws")
region = aws_config.require("region")

Set structured values with a namespaced path: Keep the namespace on the top-level segment.

pulumi config set --path 'my-infra:data.retentionDays' 30
pulumi config set --path 'my-infra:cidrs[0]' 10.0.0.0/16

What to Watch Out For

• The namespace is the name: field in Pulumi.yaml, not the stack name and not the folder name.
• In code, pulumi.Config() defaults to the project namespace; on the CLI, always namespace provider keys like aws:region explicitly.
• Renaming the project (name: in Pulumi.yaml) orphans existing namespaced keys — you must re-set them under the new namespace.
• Use --secret for anything sensitive so it is stored encrypted, never in plaintext in Pulumi.<stack>.yaml.
• Quote --path expressions to stop your shell from expanding brackets or dots.

Related Guides

• Pulumi Error: ‘unmarshalling properties’ — Troubleshooting Guide
• Pulumi Error: ‘no valid credential sources for AWS Provider’ — Troubleshooting Guide
• Pulumi Error: ‘failed to decrypt configuration’ — Troubleshooting Guide