How Do I Debug This Error: Organization Name Must Be 'Organization'

Introduction

When using Pulumi with a self-managed (DIY) backend, you might encounter the error: “organization name must be ‘organization’”. This error can be confusing if you’re not familiar with how Pulumi manages projects and stacks across different backends. In this guide, we’ll help you understand and resolve this error.

What’s Actually Happening?

Pulumi supports two types of backends for storing your infrastructure state:

1. Service Backend: The hosted Pulumi Cloud service (app.pulumi.com) or a self-hosted Pulumi service
2. DIY Backend: Self-managed storage like local filesystem, S3, Azure Blob Storage, etc.

In DIY backends, all projects are placed under a virtual organization named literally “organization”. This is a fixed value and cannot be changed. When you try to reference a stack with an organization name other than “organization”, you’ll encounter this error.

Explanation

Understand Stack References

When referencing stacks in Pulumi, you can use fully-qualified names in the format:

<org>/<project>/<stack>

For DIY backends, the <org> part must always be “organization”.

Check How You’re Referencing Stacks

The error typically occurs in these scenarios:

1. Incorrect Stack Reference: You’re trying to reference a stack using an organization name other than “organization”

   // Incorrect
   const otherStack = new pulumi.StackReference("my-org/my-project/my-stack");
   
   // Correct for DIY backend
   const otherStack = new pulumi.StackReference("organization/my-project/my-stack");
   

2. Configuration Issues: Your Pulumi configuration is set up with an incorrect organization

Fix References to Use “organization”

To resolve this error:

1. Update all stack references in your code to use “organization” as the organization name
2. Use the correct format in CLI commands
3. If you’re migrating from the Pulumi Service to a DIY backend, be aware of this difference

Simplified Stack References

For convenience, if you’re within a project directory, you can use these shorthand forms:

pulumi stack select organization/<stack>  # If inside the project directory
pulumi stack select <stack>               # If inside the project directory

Common Scenarios

Migration Between Backends

If you’re migrating from the Pulumi Service to a DIY backend, you’ll need to update any stack references to use “organization” instead of your previous organization name.

Multiple Projects in DIY Backend

With DIY backends, project-scoped stacks are supported (as of Pulumi v3.61.0+). This allows you to use the same stack names across different projects without conflicts. Each project’s stacks are stored in a separate namespace.

organization/project1/dev
organization/project2/dev

Working with Legacy DIY Backends

If you’re using an older DIY backend that hasn’t been upgraded to support project-scoped stacks, you might need to use the pulumi state upgrade command to upgrade your backend format.

Wrapping Up

The “organization name must be ‘organization’” error is specific to DIY backends in Pulumi. It’s a reminder of the architectural difference between the Pulumi Service and DIY backends. By understanding this distinction and ensuring all stack references use “organization” as the organization name, you can easily resolve this error and continue managing your infrastructure with Pulumi.