{"record":{"id":"715c975aeeadbb3b","repo":"pulumi/pulumi","slug":"only-one-root-pulumi-stack-may-be-active-at-once","errorCode":null,"errorMessage":"Only one root Pulumi Stack may be active at once","messagePattern":"Only one root Pulumi Stack may be active at once","errorType":"exception","errorClass":"Exception","httpStatus":null,"severity":"error","filePath":"sdk/python/lib/pulumi/runtime/stack.py","lineNumber":286,"sourceCode":"\n    await _load_monitor_feature_support()\n    await run_pulumi_func(run)\n\n\nclass Stack(ComponentResource):\n    \"\"\"\n    A synthetic stack component that automatically parents resources as the program runs.\n    \"\"\"\n\n    outputs: dict[str, Any]\n\n    def __init__(\n        self,\n        func: Optional[Callable[[], Optional[Awaitable[None]]]] = None,\n    ) -> None:\n        # Ensure we don't already have a stack registered.\n        if get_root_resource() is not None:\n            raise Exception(\"Only one root Pulumi Stack may be active at once\")\n\n        # Now invoke the registration to begin creating this resource.\n        name = f\"{get_project()}-{get_stack()}\"\n        super().__init__(\"pulumi:pulumi:Stack\", name, None, None)\n\n        self.outputs = {}\n        self._async_program: Optional[_AsyncProgram] = None\n        self._async_program_registration_closed = False\n        self._outputs_registered = False\n        set_root_resource(self)\n\n        # Stack historically invoked the program callback and finalized outputs\n        # in its constructor. Keep Stack(func) working for direct callers of this\n        # importable internal class. run_in_stack now creates Stack() and awaits\n        # user code itself.\n        if func is not None:\n            self._run_legacy_callback(func)\n","sourceCodeStart":268,"sourceCodeEnd":304,"githubUrl":"https://github.com/pulumi/pulumi/blob/793f7b2e160db4321fb7fb6b0607461e01cb251e/sdk/python/lib/pulumi/runtime/stack.py#L268-L304","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Remove the manual Stack construction — the Pulumi engine creates the root stack automatically","In tests, tear down / reset the runtime (fresh process or runtime reset) between program runs","Guard stack creation behind `if get_root_resource() is None:`"],"exampleFix":"// before\nstack = Stack(my_program)  # second Stack in same process\n// after\n# let the engine create the root stack; call my_program() at module top level instead","handlingStrategy":"validation","validationCode":"from pulumi.runtime import get_root_resource\nif get_root_resource() is not None:\n    raise RuntimeError('A root stack already exists; do not create another')","typeGuard":"def root_stack_active() -> bool:\n    from pulumi.runtime import get_root_resource\n    return get_root_resource() is not None","tryCatchPattern":"try:\n    Stack(my_program)\nexcept Exception as e:\n    if 'Only one root Pulumi Stack' in str(e):\n        logger.error('Remove manual Stack construction; the engine creates it')\n    raise","preventionTips":["Never construct pulumi.runtime.Stack manually in program code","Keep the program entry point single and idempotent per process","Reset the runtime (or use a fresh process) between repeated test runs"],"tags":["python","stack","lifecycle"],"backgroundTag":"duplicate-root-stack","analyzedSha":"793f7b2e160db4321fb7fb6b0607461e01cb251e","analyzedAt":"2026-08-31T09:36:43.099Z","schemaVersion":2},"datasetVersion":"2026-08-31T14:17:45.589Z"}