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

Overview

error: update failed is the terminal message Pulumi prints when a pulumi up cannot complete. It is a summary, not a root cause: the CLI ran the deployment, one or more resource operations returned an error from the underlying provider, and Pulumi rolled the operation to a stop. The real detail is in the lines above this message — the per-resource diagnostics — while error: update failed is just the non-zero exit banner.

A typical tail of the output looks like this:

Diagnostics:
  aws:ec2:Instance (web):
    error: 1 error occurred:
        * creating EC2 Instance: InvalidParameterValue: Value (t2.mega) for parameter instanceType is invalid. Specify a valid instance type.
        status code: 400, request id: 8f2c...

  pulumi:pulumi:Stack (myproject-dev):

error: update failed

Because pulumi up operates as a graph, some resources may have already been created or modified before the failing resource aborted the run. That partial-apply behavior is what makes this error more than a simple syntax problem — your stack state and your real cloud infrastructure can be out of sync until you fix and re-run.

Symptoms

• pulumi up exits with a non-zero status and the last line is error: update failed.
• One or more resources show **failed** or **creating failed** in the update table.
• Provider-specific errors (AWS InvalidParameterValue, AccessDenied, ThrottlingException; Azure Conflict; GCP googleapi: Error 403) appear in the Diagnostics: block.
• Subsequent runs report resources in a creating or updating state that never finished.
• pulumi stack shows a resource count that does not match what you expect.
• In CI, the job fails but some cloud resources were still created (partial spend).

Common Root Causes

1. Provider rejected the resource input

The most common cause: the cloud API returned a 4xx because a property value is invalid, out of range, or unsupported in the region.

* creating EC2 Instance: InvalidParameterValue: Value (t2.mega) for parameter instanceType is invalid.

The Pulumi program is syntactically fine; the API said no.

2. Insufficient IAM permissions

The credentials Pulumi is using lack permission for the specific action. This surfaces mid-update, often after other resources succeed.

* creating IAM Role: AccessDenied: User: arn:aws:iam::123456789012:user/ci-deployer is not authorized to perform: iam:CreateRole

3. Dependency or ordering failure

A resource fails because a resource it depends on failed or produced an unusable output (empty string, null ID). Pulumi cancels downstream resources with error: creating ... : resource ... was not created.

4. API throttling or transient cloud errors

Large stacks hit rate limits. AWS returns ThrottlingException / RequestLimitExceeded; the resource fails even though the config is correct.

5. Provider bug or eventual-consistency race

The provider polls for a resource that the cloud reports as ready but is not yet usable — e.g. an IAM role not propagated before an EC2 instance profile references it. Reruns often succeed.

6. Quota or capacity limits

VcpuLimitExceeded, InsufficientInstanceCapacity, or address-limit errors reject creation regardless of config correctness.

How to Diagnose

Read the diagnostics above the banner first — that is where the actionable message lives.

Re-run with full detail and provider logging:

pulumi up --logtostderr --logflow -v=9 2> pulumi-debug.log

Inspect what Pulumi thinks is in state versus reality:

pulumi stack --show-urns
pulumi stack export > stack.json

Cross-check against the real cloud with the native CLI. For the AWS example above:

aws ec2 describe-instances \
  --filters "Name=tag:Name,Values=web" \
  --region us-east-1

Confirm the identity Pulumi is actually using:

aws sts get-caller-identity

If you suspect throttling, grep the debug log:

grep -Ei 'throttl|RequestLimit|rate exceeded' pulumi-debug.log

Fixes

Cause 1 — bad input: Correct the offending property in your program and re-run. For the instance-type example, set a valid type and pulumi up again.

pulumi up

Cause 2 — IAM: Grant the missing action to the deploy principal, then re-run. Verify the policy covers the exact action in the error (iam:CreateRole above), not just a wildcard you assumed was attached.

Cause 3 — dependency failure: Fix the upstream resource that failed first; downstream resources usually succeed on the next run. If Pulumi left an output empty, add an explicit dependsOn so ordering is deterministic.

Cause 4 — throttling: Re-run — Pulumi is idempotent and will only retry the failed/pending resources. To reduce contention on large stacks, lower parallelism:

pulumi up --parallel 4

Cause 5 — eventual consistency: Simply re-running pulumi up resolves most propagation races. For chronic cases add dependsOn or a small provider-level retry.

Cause 6 — quota: Request a limit increase, or change region/instance family, then re-run.

If a failed create left a half-provisioned resource that now blocks progress, refresh state to reconcile with the cloud before retrying:

pulumi refresh
pulumi up

What to Watch Out For

• error: update failed is never the real error — always scroll up to the Diagnostics: block.
• Partial applies are normal. After a failure, assume some resources were created and check for orphaned/billable infrastructure before deleting the stack.
• Do not pulumi destroy a stack to “start clean” after a partial failure without reviewing state — you can strand resources Pulumi no longer tracks.
• Set --parallel conservatively in CI for large stacks to avoid self-inflicted throttling.
• Pin provider versions so a provider upgrade does not change validation behavior between runs.
• Run pulumi refresh if your last update was interrupted, so drift does not compound into the next up.

Related Guides

• Pulumi Error: ‘inputs to import do not match’ — Troubleshooting Guide
• Pulumi Error: ‘conflict: another update is in progress’ — Troubleshooting Guide
• IaC Testing Strategies That Actually Work