Pulumi unexpected replacement (delete-create) in CI

By Kaveh Alemi·Latchkey

The Pulumi plan shows a resource marked for replacement (delete then create) rather than an in-place update. A change touched a property the provider cannot modify in place, so Pulumi plans to replace the resource, which can cause downtime or data loss.

What this error means

A pulumi preview or pulumi up shows "~ replace" or a "+-" line for a resource, and the diff highlights a property annotated as forcing replacement.

    ~ aws:rds/instance:Instance app-db replace
      ~ engineVersion: "14.7" => "15.3"
      [diff: ~engineVersion]; this change requires replacing the resource

Common causes

A change to an immutable property

The provider marks the changed property (name, engine version, availability zone) as replace-only, so it cannot be updated in place.

A dependency change cascaded into a replacement

An upstream resource was replaced, forcing replacement of resources that reference its immutable output.

How to fix it

Read the [diff] and decide on replacement

1. Find the property annotated as forcing replacement in the diff.
2. If replacement is unacceptable, avoid changing that property or use provider features that update in place.
3. If replacement is intended, plan for downtime and data handling before applying.

pulumi preview --diff

Create before delete to reduce downtime

Set the resource to be created before the old one is deleted so a replacement does not leave a gap.

// TypeScript
new aws.rds.Instance('app-db', { /* ... */ }, {
  replaceOnChanges: ['engineVersion'],
  deleteBeforeReplace: false,
});

How to prevent it

• Review pulumi preview --diff before merging changes to stateful resources.
• Know which properties force replacement for your providers.
• Use create-before-delete for resources where downtime is costly.

Frequently asked questions

Related guides

References

• Terraform documentation
• GitHub Actions documentation