What causes "The application has not been initialized." in microsoft/aspire?

Await the factory's StartAsync/CreateAsync before calling GetStartedApplication, e.g. var app = await factory.StartAsync(...); then use app or factory.GetStartedApplication().

microsoft/aspire · error · InvalidOperationException

The application has not been initialized.

Error message

The application has not been initialized.

What it means

Thrown by ThrowIfNotInitialized when GetStartedApplication (or members relying on it) is called before the application factory has finished starting successfully. The factory tracks startup completion via _startedTcs; accessing the application too early or after a failed start raises this error.

Solutions

Await the factory's StartAsync/CreateAsync before calling GetStartedApplication, e.g. var app = await factory.StartAsync(...); then use app or factory.GetStartedApplication().
Inspect earlier logs/exceptions: if startup failed, the real error will have surfaced via the factory's exception channel — fix that first.
Restructure tests so the started application is obtained inside the async test method rather than a constructor.
Increase the startup timeout via TestingOptions/Environment (e.g. Aspire hosting test timeout env var) if startup is merely slow.

Example fix

// before
var factory = DistributedApplicationTesting.CreateAsync<Projects.AppHost>();
var app = factory.GetStartedApplication(); // not initialized yet
// after
var factory = await DistributedApplicationTesting.CreateAsync<Projects.AppHost>();
await factory.StartAsync();
var app = factory.GetStartedApplication();

Defensive patterns

Strategy: try-catch

Try / catch

var app = await appHost.StartAsync(); // always await before GetStartedApplication
// if you must poll:
try
{
    var started = appHost.GetStartedApplication();
}
catch (InvalidOperationException ex) when (ex.Message.Contains("has not been initialized"))
{
    // startup not complete or failed; await start task or inspect startup exception
}

Prevention

Always await CreateAsync/StartAsync before accessing the application or resources.
Never call GetStartedApplication from constructors or field initializers.
If startup is slow, raise the configured startup timeout instead of polling.

When it happens

Trigger: Calling factory.GetStartedApplication() (or accessing HttpClient/Resources that depend on it) before awaiting StartAsync/CreateAsync completion, or after startup failed so _startedTcs never completed successfully.

Common situations: Not awaiting the start task before asserting on resources; using the factory in a constructor or field initializer where the async start hasn't finished; startup crashed earlier (e.g. a container failed) so the app never initialized; fire-and-forget start without awaiting.

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/42c6d2759f41424d. Report an issue: GitHub.

Appendix: source

Thrown at src/Aspire.Hosting.Testing/DistributedApplicationFactory.cs:454

    private void OnEntryPointExit(Exception? exception)
    {
        if (exception is not null)
        {
            _exitTcs.TrySetException(exception);
            OnException(exception);
        }
        else
        {
            _exitTcs.TrySetResult();
        }
    }

    private void ThrowIfNotInitialized()
    {
        if (!_startedTcs.Task.IsCompletedSuccessfully)
        {
            throw new InvalidOperationException("The application has not been initialized.");
        }
    }

    private DistributedApplication GetStartedApplication()
    {
        ThrowIfNotInitialized();
        return _appTcs.Task.GetAwaiter().GetResult();
    }

    private void OnException(Exception exception)
    {
        _appTcs.TrySetException(exception);
        _builderTcs.TrySetException(exception);
        _startedTcs.TrySetException(exception);
    }

    private void OnDisposed()
    {

View on GitHub (pinned to 25830f84bd)