🚨 Pulumi Error: 'Duplicate resource URN ...; try giving it a unique name' — Cause, Fix, and Troubleshooting Guide

Overview

error: Duplicate resource URN ...; try giving it a unique name means your program declared two resources that resolve to the same URN. A URN (Uniform Resource Name) is how Pulumi uniquely identifies each resource in a stack, and it is built from the stack name, project name, resource type, and the logical name you pass as the first argument to the constructor — plus any parent prefix.

error: Duplicate resource URN 'urn:pulumi:dev::myproject::aws:s3/bucket:Bucket::my-bucket'; try giving it a unique name

Because the URN embeds type + name, two resources of the same type with the same logical name collide. Note that this is the logical name (the string you give Pulumi), not the physical cloud name — you can have two buckets with different bucket: properties but they will still collide if you passed them the same logical name.

Symptoms

• pulumi preview or pulumi up fails before any changes with Duplicate resource URN '...'; try giving it a unique name.
• The URN in the message ends in ::<name> where <name> is used twice in your program.
• You just copy-pasted a resource block, added a loop, or refactored into a component.
• The two colliding resources are the same type (e.g. both aws:s3/bucket:Bucket).

Common Root Causes

1. Copy-pasted resource with the same logical name

The classic mistake: duplicating a block and forgetting to change the first argument.

const a = new aws.s3.Bucket("my-bucket", {});
const b = new aws.s3.Bucket("my-bucket", {});  // same type + name => duplicate URN

2. A loop that reuses a constant name

Iterating over a list but passing a fixed literal instead of an index- or item-derived name, so every iteration produces the same URN.

for (const env of ["dev", "stg"]) {
  new aws.s3.Bucket("bucket", {});  // "bucket" repeats every iteration
}

3. The same component instantiated twice with one name

Instantiating a ComponentResource twice with the same name, or creating a child resource inside a component whose name is not derived from the component’s name.

4. A merged branch or shared module declaring the same resource twice

Two imports/modules each register a resource with an identical type and name in the same stack.

How to Diagnose

The URN tells you exactly what collided — read it right to left: ...::<type>::<name>. Search your program for that logical name and type:

grep -rn '"my-bucket"' .

Preview to confirm the collision without mutating anything:

pulumi preview

If you cannot spot the second declaration, list existing resources in the stack to distinguish an in-program duplicate from a state issue:

pulumi stack --show-urns

Fixes

Give each resource a unique logical name. The direct fix — rename the second resource so its URN differs:

const primary   = new aws.s3.Bucket("my-bucket", {});
const secondary = new aws.s3.Bucket("my-bucket-logs", {});

Derive names from the loop variable. When creating resources in a loop, incorporate the item or index into the name so every URN is unique:

for (const env of ["dev", "stg", "prod"]) {
  new aws.s3.Bucket(`assets-${env}`, {});
}

Set an explicit physical name separately from the logical name. If you need a specific cloud name but a unique Pulumi name, keep the logical names distinct and set the physical name via the resource property:

const bucket = new aws.s3.BucketV2("assets-prod", {
  bucket: "acme-assets-prod",   // physical name; logical name stays unique
});

Prefix child resources with the parent/component name. Inside a ComponentResource, build child names from name so multiple component instances do not collide:

new aws.s3.Bucket(`${name}-data`, {}, { parent: this });

In Pulumi YAML, use unique map keys. Each resource key under resources: must be unique — rename the duplicate key:

resources:
  myBucket:
    type: aws:s3:BucketV2
  myBucketLogs:      # was a second "myBucket" — now unique
    type: aws:s3:BucketV2

What to Watch Out For

• The URN uses the logical name (the constructor’s first argument), not the physical cloud name — renaming only the bucket: property will not fix a duplicate URN.
• Renaming the logical name of an already-deployed resource makes Pulumi see it as a delete-and-replace. Use the aliases resource option to rename without recreating.
• Names only need to be unique within a type and parent — aws:s3/bucket:Bucket named data and aws:sqs/queue:Queue named data do not collide.
• When looping, never pass a literal name; always fold in the index or item value.
• After fixing, run pulumi preview to confirm the collision is gone before applying.

Related Guides

• Pulumi Error: ‘resource already exists’ — Troubleshooting Guide
• Pulumi Error: ‘unknown resource type’ — Troubleshooting Guide
• Pulumi Error: ‘failed to register new resource’ — Troubleshooting Guide