{"record":{"id":"a32b62e650f8daba","repo":"microsoft/aspire","slug":"builder-connection-not-initialized","errorCode":null,"errorMessage":"Builder connection not initialized.","messagePattern":"Builder connection not initialized\\.","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"src/Aspire.Hosting.CodeGeneration.Python/PythonModuleBuilder.cs","lineNumber":1780,"sourceCode":"        \"\"\";\n\n    /// <summary>\n    /// The <c>DistributedApplicationBuilder</c> Python class definition for the generated SDK.\n    /// </summary>\n    public const string DistributedApplicationBuilder = \"\"\"\n        class DistributedApplicationBuilder:\n            '''Type class for DistributedApplicationBuilder.'''\n\n            def __init__(self, client: AspireClient, options: CreateBuilderOptions) -> None:\n                self._handle = None\n                self._client = client\n                self._options = options\n\n            @property\n            def handle(self) -> Handle:\n                '''Gets the underlying handle for the builder.'''\n                if not self._handle:\n                    raise RuntimeError(\"Builder connection not initialized.\")\n                return self._handle\n\n            def __enter__(self) -> DistributedApplicationBuilder:\n                self._handle = self._client.invoke_capability(\n                    'Aspire.Hosting/createBuilder',\n                    {'argsOrOptions': self._options}\n                )\n                return self\n\n            def __exit__(self, exc_type, exc_value, traceback) -> None:\n                self._client.disconnect()\n\n            def run(self, *, timeout: int | None = None) -> None:\n                '''Builds and runs the distributed application.'''\n                app = self.build()\n                app.run(timeout=timeout)\n\n        \"\"\";","sourceCodeStart":1762,"sourceCodeEnd":1798,"githubUrl":"https://github.com/microsoft/aspire/blob/25830f84bd145686607ad00c057b3f84e2e51d43/src/Aspire.Hosting.CodeGeneration.Python/PythonModuleBuilder.cs#L1762-L1798","documentation":"The DistributedApplicationBuilder Python wrapper lazily connects inside `__enter__`; accessing `.handle` before the builder has entered its context (which invokes 'Aspire.Hosting/createBuilder') finds no handle and raises RuntimeError.","triggerScenarios":"Reading `builder.handle` before `with DistributedApplicationBuilder(...) as builder:` completes, or using the builder outside a with-block without an explicit connect call.","commonSituations":"Calling add/get helpers on the builder before the context manager body runs; forgetting the `with` statement entirely; an exception during `__enter__` leaving `_handle` unset.","solutions":["Use the builder inside a `with` block and only touch `.handle` inside that block.","Check for exceptions raised during enter that prevented handle creation.","If the API allows explicit connect, call it before accessing `.handle`."],"exampleFix":"# before\nbuilder = DistributedApplicationBuilder(options)\nprint(builder.handle)\n# after\nwith DistributedApplicationBuilder(options) as builder:\n    print(builder.handle)","handlingStrategy":"try-catch","validationCode":"if getattr(builder, \"_handle\", None) is None:\n    raise RuntimeError(\"enter the builder context before accessing handle\")","typeGuard":"def is_connected(builder) -> bool:\n    return bool(getattr(builder, \"handle\", None))","tryCatchPattern":"try:\n    handle = builder.handle\nexcept RuntimeError:\n    raise RuntimeError(\"call `with DistributedApplicationBuilder(...)` before using the builder\")","preventionTips":["Always use the builder inside a `with` block.","Access .handle only inside the context body.","Handle enter-time exceptions; they leave the handle unset."],"tags":["python","lifecycle","uninitialized","builder"],"backgroundTag":"invalid-state-transition","analyzedSha":"25830f84bd145686607ad00c057b3f84e2e51d43","analyzedAt":"2026-09-16T11:10:06.193Z","contentChangedAt":"2026-09-16T11:10:06.193Z","schemaVersion":2},"datasetVersion":"2026-09-21T04:17:39.646Z"}