What causes "Builder connection not initialized." in microsoft/aspire?

Use the builder inside a `with` block and only touch `.handle` inside that block.

microsoft/aspire · error · RuntimeError

Builder connection not initialized.

Error message

Builder connection not initialized.

What it means

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.

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`.

Example fix

# before
builder = DistributedApplicationBuilder(options)
print(builder.handle)
# after
with DistributedApplicationBuilder(options) as builder:
    print(builder.handle)

Defensive patterns

Strategy: try-catch

Validate before calling

if getattr(builder, "_handle", None) is None:
    raise RuntimeError("enter the builder context before accessing handle")

Type guard

def is_connected(builder) -> bool:
    return bool(getattr(builder, "handle", None))

Try / catch

try:
    handle = builder.handle
except RuntimeError:
    raise RuntimeError("call `with DistributedApplicationBuilder(...)` before using the builder")

Prevention

Always use the builder inside a `with` block.
Access .handle only inside the context body.
Handle enter-time exceptions; they leave the handle unset.

When it happens

Trigger: Reading `builder.handle` before `with DistributedApplicationBuilder(...) as builder:` completes, or using the builder outside a with-block without an explicit connect call.

Common situations: 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.

Understand the failure class

Background: "Invalid state transition" errors: "status must be X, actually Y", "already rejected/charging/uninstalled", "cannot ... while running" — what they mean when a library rejects your call — this error's family across 31 libraries.

Related errors

AI-assisted analysis of microsoft/aspire@25830f84bd (2026-09-16). Data as JSON: /api/errors/a32b62e650f8daba. Report an issue: GitHub.

Appendix: source

Thrown at src/Aspire.Hosting.CodeGeneration.Python/PythonModuleBuilder.cs:1780

        """;

    /// <summary>
    /// The <c>DistributedApplicationBuilder</c> Python class definition for the generated SDK.
    /// </summary>
    public const string DistributedApplicationBuilder = """
        class DistributedApplicationBuilder:
            '''Type class for DistributedApplicationBuilder.'''

            def __init__(self, client: AspireClient, options: CreateBuilderOptions) -> None:
                self._handle = None
                self._client = client
                self._options = options

            @property
            def handle(self) -> Handle:
                '''Gets the underlying handle for the builder.'''
                if not self._handle:
                    raise RuntimeError("Builder connection not initialized.")
                return self._handle

            def __enter__(self) -> DistributedApplicationBuilder:
                self._handle = self._client.invoke_capability(
                    'Aspire.Hosting/createBuilder',
                    {'argsOrOptions': self._options}
                )
                return self

            def __exit__(self, exc_type, exc_value, traceback) -> None:
                self._client.disconnect()

            def run(self, *, timeout: int | None = None) -> None:
                '''Builds and runs the distributed application.'''
                app = self.build()
                app.run(timeout=timeout)

        """;

View on GitHub (pinned to 25830f84bd)