🧱 Pulumi Error: 'unknown stack' StackReference Output Not Found

Exact Error Message

error: Preview failed: unknown stack 'acmecorp/networking/prod'; are you sure the stack exists and you have access?
    at new StackReference (.../@pulumi/pulumi/stackReference.ts)
    at Object.<anonymous> (.../index.ts:12:19)

You may also see a variant where the stack resolves but a specific output does not:

error: Cannot read properties of undefined (reading 'apply')
  (the requested output 'vpcId' was not found on stack reference 'acmecorp/networking/prod')

What It Means

A StackReference lets one Pulumi stack read the outputs of another. The name you pass must be a fully-qualified stack name in the form <org>/<project>/<stack> (for the Pulumi Cloud backend) or <project>/<stack> for the local/self-managed backend. When Pulumi cannot locate a stack with that exact triple, it raises unknown stack. The consuming program never even reaches the resource-provisioning phase, so the whole preview or update aborts.

The second variant means the stack was found, but the output key you requested was never exported from that stack, so getOutput() returns undefined. That is a data-shape problem, not an access problem.

Common Causes

• The org, project, or stack segment is misspelled, or the org prefix is omitted entirely on the Pulumi Cloud backend.
• The producing stack has never been deployed, so it has no outputs recorded in state yet.
• The output was renamed or never exported with export/ctx.Export/pulumi.export in the producing program.
• The two stacks live in different backends (one in Pulumi Cloud, one in an S3 self-managed backend), so the reference cannot resolve.
• The credentials or access token in the current environment cannot see the referenced stack (different org, or a token without membership).
• The project name in Pulumi.yaml of the producer differs from what you typed in the reference.

Diagnostic Commands

List the stacks the current login can actually see and confirm the exact fully-qualified name:

pulumi stack ls --all

Confirm you are pointed at the backend that holds the producing stack:

pulumi whoami -v

Inspect the producing stack’s outputs directly to verify the key name and that it is populated:

pulumi stack output --stack acmecorp/networking/prod --show-secrets

Dump the full output map as JSON when a nested key is in doubt:

pulumi stack output --stack acmecorp/networking/prod --json

Step-by-Step Resolution

1. Copy the exact stack name from pulumi stack ls --all and paste it into the StackReference constructor. On Pulumi Cloud the org prefix is mandatory:

const net = new pulumi.StackReference("acmecorp/networking/prod");
export const vpcId = net.getOutput("vpcId");

2. If the stack exists but the output is missing, add the export to the producing program and redeploy it before consuming:

// in the networking project
export const vpcId = vpc.id;

pulumi up --stack acmecorp/networking/prod

3. Verify both stacks use the same backend. If the producer lives in S3, log the consumer into the same place:

pulumi login s3://my-pulumi-state-bucket

4. For a required output that must exist, use requireOutput so a missing key fails loudly instead of silently returning undefined:

const vpcId = net.requireOutput("vpcId");

5. Re-run the preview and confirm it resolves the reference cleanly:

pulumi preview

Prevention

• Store fully-qualified stack names in config (pulumi config set networkStack acmecorp/networking/prod) instead of hard-coding them, so environments stay consistent.
• Keep related stacks in the same backend and organization to avoid cross-backend reference failures.
• Treat exported outputs as a public contract: never rename or remove one without updating every consumer.
• Deploy producer stacks before consumer stacks in your CI pipeline ordering.
• Use requireOutput/requireOutputValue for outputs your program cannot run without, so failures surface at preview time.

Related Errors

• could not decrypt configuration value — a secrets/passphrase problem, not a missing stack.
• no stack selected; run pulumi stack select — no current stack, unrelated to references.
• error: getting secrets manager — backend/secrets provider mismatch on the referenced stack.
• Cannot read properties of undefined — the reference resolved but the requested output key is absent.

Frequently Asked Questions

Why does my StackReference work locally but fail in CI? CI usually logs into a different backend or uses a token scoped to a different org, so the fully-qualified name cannot be resolved. Run pulumi whoami -v in the pipeline to confirm the backend and login match your workstation.

Do I need the org prefix in the stack name? On the Pulumi Cloud backend yes, the format is org/project/stack. On a self-managed backend (S3/GCS/Azure/local) there is no org, so you use project/stack.

How do I read a nested output from another stack? Use getOutput("key") and chain .apply() for nested access, or call pulumi stack output --json to see the exact shape before you reference it.

Can I reference a stack that has never been deployed? No. Outputs only exist after a successful pulumi up, so deploy the producer first. For repeatable multi-stack patterns, browse the Pulumi prompt templates.

What is the fastest way to confirm the name is right? Run pulumi stack ls --all and copy the name verbatim. Typos in the org or project segment are the single most common cause. See more Pulumi guides.