🚨 Pulumi Error: 'error: Preview failed' — Cause, Fix, and Troubleshooting Guide

Overview

error: Preview failed is printed when pulumi preview (or the preview phase that runs at the start of pulumi up) cannot build the resource graph. Unlike an update failure, nothing has been changed in your cloud — preview is read-only. The failure happens before any resource operation, while Pulumi is running your program, evaluating configuration, resolving outputs, and registering the intended resources with the engine.

The banner sits under the specific diagnostics:

Diagnostics:
  pulumi:pulumi:Stack (myproject-dev):
    error: Missing required configuration variable 'myproject:dbPassword'
        please set a value using the command `pulumi config set myproject:dbPassword <value>`

error: Preview failed

Because preview executes your actual program, most causes are code, config, or plugin problems — not cloud-side errors. It is the cheapest place to catch mistakes, which is exactly why the message matters: a clean preview is a precondition for a safe up.

Symptoms

• pulumi preview or pulumi up aborts in the preview phase with error: Preview failed.
• Diagnostics reference missing config, an unhandled exception in your program, or a plugin that could not start.
• No resources show as creating/updating — the update table never renders.
• Language runtime stack traces (Python Traceback, Node TypeError, Go panic) appear above the banner.
• Missing required configuration variable or unknown provider messages.
• CI fails on preview even though the last successful apply was unchanged — usually a config or dependency drift.

Common Root Causes

1. Missing or unset configuration value

Your program reads a required config key that is not set for the current stack.

error: Missing required configuration variable 'myproject:dbPassword'

2. An exception in your program

Preview runs your language code. Any unhandled error — a null dereference, a bad file read, a failed import — aborts registration.

    error: Running program '/app' failed with an unhandled exception:
    TypeError: Cannot read properties of undefined (reading 'id')

3. Provider plugin missing or failed to start

If a required provider plugin is not installed or cannot initialize, the engine cannot describe the resources.

pulumi preview
# error: could not load plugin for aws provider

4. Invalid or malformed stack configuration

A corrupt Pulumi.<stack>.yaml, a secret that cannot be decrypted, or a config value of the wrong shape (string where an object is expected) fails during config evaluation.

5. Programmatic use of unknown/preview outputs

Reading .apply() outputs as if they were concrete during preview — e.g. using a resource ID in a string that must be known at plan time — raises errors because those values are unknown until apply.

6. Wrong or uninitialized stack

Running preview against a stack that was never pulumi up’d, or selecting the wrong stack, so expected config/state is absent.

How to Diagnose

Confirm which stack you are on and what config it has:

pulumi stack
pulumi config

Re-run preview with verbose engine and language-host logging:

pulumi preview --logtostderr -v=9 2> preview-debug.log

For a program exception, run the entrypoint outside Pulumi to isolate a plain code bug from a Pulumi-specific one:

# Node
node index.js
# Python (inside the venv Pulumi uses)
python __main__.py

Check that required plugins are present:

pulumi plugin ls

Validate the stack config file is well-formed YAML and decryptable:

pulumi config --show-secrets

Fixes

Cause 1 — missing config: Set the value on the correct stack. Use --secret for sensitive values.

pulumi config set myproject:dbPassword 's3cr3t' --secret
pulumi preview

Cause 2 — program exception: Fix the code path in the traceback. Guard optional values and validate inputs before referencing them. Re-run preview once the entrypoint runs cleanly on its own.

Cause 3 — plugin missing: Install the provider plugin and re-run.

pulumi plugin install resource aws 6.40.0
pulumi preview

Cause 4 — bad config: Correct the malformed Pulumi.<stack>.yaml. If a secret cannot be decrypted, confirm you are using the same secrets provider/passphrase the config was encrypted with.

Cause 5 — unknown outputs: Move logic that depends on resource outputs inside .apply() / Output.apply, and never require an unknown value to be concrete during preview. Provide defaults so preview can render.

Cause 6 — wrong stack: Select or initialize the intended stack.

pulumi stack select dev
# or, for a brand-new stack:
pulumi stack init dev

What to Watch Out For

• Preview is read-only — a failed preview never touched your cloud, so debug freely.
• Treat error: Preview failed as a program/config problem first, not an infrastructure problem.
• Keep required config documented; use pulumi config in CI as a pre-flight check before preview.
• Do not call external APIs or read outputs eagerly in your program — that turns preview into a runtime that can fail unpredictably.
• Pin provider plugin versions so preview behavior is reproducible across machines and CI runners.
• A green preview does not guarantee a green apply, but a red preview always blocks one — fix it first.

Related Guides

• Pulumi Error: ‘no resource plugin found’ — Troubleshooting Guide
• Managing Secrets in Infrastructure as Code
• IaC Testing Strategies That Actually Work