pulumi/pulumi · error · Exception

Only one root Pulumi Stack may be active at once

Error message

Only one root Pulumi Stack may be active at once

What it means

The Pulumi engine supports exactly one root Stack resource per process. Stack.__init__ checks get_root_resource() and raises if a root stack is already registered, because a second registration would corrupt resource and output accounting.

Source

Thrown at sdk/python/lib/pulumi/runtime/stack.py:286

    await _load_monitor_feature_support()
    await run_pulumi_func(run)


class Stack(ComponentResource):
    """
    A synthetic stack component that automatically parents resources as the program runs.
    """

    outputs: dict[str, Any]

    def __init__(
        self,
        func: Optional[Callable[[], Optional[Awaitable[None]]]] = None,
    ) -> None:
        # Ensure we don't already have a stack registered.
        if get_root_resource() is not None:
            raise Exception("Only one root Pulumi Stack may be active at once")

        # Now invoke the registration to begin creating this resource.
        name = f"{get_project()}-{get_stack()}"
        super().__init__("pulumi:pulumi:Stack", name, None, None)

        self.outputs = {}
        self._async_program: Optional[_AsyncProgram] = None
        self._async_program_registration_closed = False
        self._outputs_registered = False
        set_root_resource(self)

        # Stack historically invoked the program callback and finalized outputs
        # in its constructor. Keep Stack(func) working for direct callers of this
        # importable internal class. run_in_stack now creates Stack() and awaits
        # user code itself.
        if func is not None:
            self._run_legacy_callback(func)

View on GitHub (pinned to 793f7b2e16)

Solutions

1. Remove the manual Stack construction — the Pulumi engine creates the root stack automatically
2. In tests, tear down / reset the runtime (fresh process or runtime reset) between program runs
3. Guard stack creation behind `if get_root_resource() is None:`

Example fix

// before
stack = Stack(my_program)  # second Stack in same process
// after
# let the engine create the root stack; call my_program() at module top level instead

from pulumi.runtime import get_root_resource
if get_root_resource() is not None:
    raise RuntimeError('A root stack already exists; do not create another')

def root_stack_active() -> bool:
    from pulumi.runtime import get_root_resource
    return get_root_resource() is not None

try:
    Stack(my_program)
except Exception as e:
    if 'Only one root Pulumi Stack' in str(e):
        logger.error('Remove manual Stack construction; the engine creates it')
    raise

When it happens

Trigger: Constructing a second `Stack()` (or calling the module-level entry that creates one) while the engine-created root stack is already active — e.g. calling `pulumi.runtime.Stack(...)` manually inside a program that already has one.

Common situations: Importing a module whose top level constructs a Stack while also using the standard `pulumi up` flow; double-invoking the program entry point in tests; accidentally calling the main function twice in the same process.

Related errors

• missing stack URN
• when debugging or running explicitly, must call Handshake be
• name must be of type 'str'
• Failed to export output. Root resource is not an instance of
• pulumi.run may only be called once

AI-assisted analysis of pulumi/pulumi@793f7b2e16 (2026-08-31). Data as JSON: /api/errors/715c975aeeadbb3b. Report an issue: GitHub.