microsoft/aspire · error · InvalidOperationException

Initial resource snapshot load has not completed. Call…

Error message

Initial resource snapshot load has not completed. Call WaitForInitialLoadAsync first.

What it means

ResourceSnapshotWatcher methods that read state (GetResource, GetResources, CaptureAllResources, WatchResourceSnapshotBatchesAsync) call EnsureInitialLoadComplete, which throws InvalidOperationException until the initial snapshot load task has completed successfully. The watcher requires callers to await WaitForInitialLoadAsync first so reads observe a consistent baseline.

Solutions

Await watcher.WaitForInitialLoadAsync() before any snapshot read or update streaming.
Handle failures of WaitForInitialLoadAsync (it propagates the initial-load exception) and reconnect/retry before reading.
If reads keep racing, restructure startup so watcher initialization is awaited before dependent services start.

Example fix

// before
var watcher = new ResourceSnapshotWatcher(connection);
var resources = watcher.GetResources(); // throws
// after
var watcher = new ResourceSnapshotWatcher(connection);
await watcher.WaitForInitialLoadAsync();
var resources = watcher.GetResources();

Defensive patterns

Strategy: validation

Validate before calling

// gate all snapshot reads on initial load
await watcher.WaitForInitialLoadAsync();
// then safe to call GetResource/GetResources/WatchResourceSnapshotBatchesAsync

Try / catch

try { await watcher.WaitForInitialLoadAsync(ct); }
catch (Exception ex) { /* initial load failed: reconnect/retry before any reads */ }

Prevention

Always await WaitForInitialLoadAsync immediately after creating the watcher
Sequence dependent services after watcher initialization completes
Watch for propagated initial-load failures — they also block reads

When it happens

Trigger: Calling GetResource/GetResources/CaptureAllResources/WatchResourceSnapshotBatchesAsync before awaiting WaitForInitialLoadAsync, or after the initial load failed/cancelled (Task not completed successfully).

Common situations: Fire-and-forget startup where reads race the initial GET from the AppHost; initial load failed due to a dropped AppHost connection so the task never completes successfully; calling snapshot APIs synchronously right after constructing the watcher.

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

Appendix: source

Thrown at src/Aspire.Cli/Backchannel/ResourceSnapshotWatcher.cs:266

                    .ToArray()
                : updates
                    .Where(update => update.Sequence > afterSequence)
                    .OrderBy(update => update.Sequence)
                    .Select(update => update.Snapshot)
                    .ToArray();

            if (snapshots.Length > 0)
            {
                yield return new ResourceSnapshotUpdateBatch(snapshots, isResync);
            }
        }
    }

    private void EnsureInitialLoadComplete()
    {
        if (!_initialLoadTcs.Task.IsCompletedSuccessfully)
        {
            throw new InvalidOperationException("Initial resource snapshot load has not completed. Call WaitForInitialLoadAsync first.");
        }
    }

    /// <summary>
    /// Gets a resource snapshot by name, or <see langword="null"/> if not found.
    /// </summary>
    public ResourceSnapshot? GetResource(string name)
    {
        EnsureInitialLoadComplete();
        lock (_resourcesLock)
        {
            return _resources.GetValueOrDefault(name);
        }
    }

    /// <summary>
    /// Gets all current resource snapshots, using <see cref="IncludeHidden"/> to determine visibility.
    /// </summary>

View on GitHub (pinned to 25830f84bd)