microsoft/aspire · error · Error

Not connected to AppHost

Error message

Not connected to AppHost

What it means

invokeCapability requires an established connection stored in this.connection. If the client is not connected (never connected, disconnected, or connect failed), it throws 'Not connected to AppHost' before validating or sending anything.

Solutions

  1. Await client.connect() and confirm it succeeds before invoking capabilities.
  2. Check socket close/error handlers to detect disconnection and reconnect before retrying invokeCapability.
  3. Ensure you invoke on the same client instance that performed the connection.
  4. Add a ready/connected guard or state check around capability calls in your app logic.

Example fix

// before
const client = new AspireClient();
client.connect(); // not awaited
const result = await client.invokeCapability('cap', {});

// after
const client = new AspireClient();
await client.connect();
if (!client.isConnected) throw new Error('connect failed');
const result = await client.invokeCapability('cap', {});
Defensive patterns

Strategy: validation

Validate before calling

if (!client.connection) {
  throw new Error('call await client.connect() before invokeCapability');
}

Type guard

function isConnected(c: AspireClient): boolean {
  return c.connection !== null;
}

Try / catch

try {
  const result = await client.invokeCapability(cap, args);
} catch (err) {
  if (String(err.message) === 'Not connected to AppHost') {
    await client.connect();
    return client.invokeCapability(cap, args);
  }
  throw err;
}

Prevention

When it happens

Trigger: Calling invokeCapability on a new AspireClient before awaiting connect(); after the socket closed (onConnectedSocketClose fired); after a failed authentication left connection null; calling from a different client instance than the one connected.

Common situations: Race where code runs before connect() resolves; connection lost mid-session due to AppHost shutdown or network drop; error during connect swallowed so the app continues invoking capabilities.

Related errors

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

Appendix: source

Thrown at src/Aspire.Hosting.CodeGeneration.TypeScript/Resources/transport.mts:1028

    }

    /**
     * Invoke an ATS capability by ID.
     *
     * Capabilities are operations exposed by [AspireExport] attributes.
     * Results are automatically wrapped in Handle objects when applicable.
     *
     * @param capabilityId - The capability ID (e.g., "Aspire.Hosting/createBuilder")
     * @param args - Arguments to pass to the capability
     * @returns The capability result, wrapped as Handle if it's a handle type
     * @throws CapabilityError if the capability fails
     */
    async invokeCapability<T = unknown>(
        capabilityId: string,
        args?: Record<string, unknown>
    ): Promise<T> {
        if (!this.connection) {
            throw new Error('Not connected to AppHost');
        }

        validateCapabilityArgs(capabilityId, args);
        const cancellationIds: string[] = [];

        try {
            const rpcArgs = await marshalTransportValue(args ?? null, this, cancellationIds, capabilityId);

            // Ref counting: The vscode-jsonrpc socket keeps Node's event loop alive.
            // We ref() during RPC calls so the process doesn't exit mid-call, and
            // unref() when idle so the process can exit naturally after all work completes.
            if (this._pendingCalls === 0) {
                this.socket?.ref();
            }
            this._pendingCalls++;

            try {
                const result = await this.connection.sendRequest(

View on GitHub (pinned to 25830f84bd)