microsoft/aspire · error · InvalidOperationException

Client must authenticate before invoking AppHost RPC…

Error message

Client must authenticate before invoking AppHost RPC methods.

What it means

Aspire.Hosting.RemoteHost exposes AppHost functionality over JSON-RPC, and every RPC entry point calls ThrowIfNotAuthenticated to gate access. This InvalidOperationException is thrown when a client invokes an RPC method (directly or via LanguageService) before completing the authentication handshake. The server rejects the call rather than executing unauthenticated work.

Solutions

Complete the authentication handshake before invoking any RPC method (send the auth message/token the server expects and wait for success).
If using a provided client API, ensure it is initialized/connected through its normal entry point rather than binding JsonRpc manually.
On reconnect (after server restart or transport drop), re-run the authentication step before resuming RPC calls.
Check server logs to confirm your client identity/token was accepted; fix the credential if authentication silently failed.

Example fix

// before
var rpc = JsonRpc.Attach(stream);
await rpc.InvokeAsync("scaffoldAppHost", "dotnet", path, name);

// after
var rpc = JsonRpc.Attach(stream);
await AuthenticateAsync(rpc); // perform handshake first
await rpc.InvokeAsync("scaffoldAppHost", "dotnet", path, name);

Defensive patterns

Strategy: validation

Validate before calling

// Before invoking any RPC, check auth state if exposed, or track it client-side:
if (!authHandshakeCompleted)
    throw new InvalidOperationException("Complete authentication before RPC calls.");

Try / catch

try { await rpc.InvokeAsync("scaffoldAppHost", ...); }
catch (InvalidOperationException ex) when (ex.Message.Contains("authenticate"))
{ /* re-authenticate then retry */ }

Prevention

Always run the auth handshake immediately after attaching the JsonRpc connection.
Centralize connection setup in one helper so RPC calls cannot be issued pre-auth.
Re-authenticate on every reconnect; never cache an assumed-authenticated state across sessions.

When it happens

Trigger: Calling any AppHost RPC method (e.g. scaffoldAppHost, getRuntimeSpec) over the JsonRpc connection without first sending the authentication message that sets JsonRpcAuthenticationState.IsAuthenticated to true.

Common situations: Custom or hand-rolled clients connecting to the remote host pipe/socket without performing the handshake; a client that lost its auth token or connected with a stale protocol; tooling that reconnects after a server restart but skips re-authentication; misordered startup where RPC calls are issued before auth completes.

Understand the failure class

Authentication and authorization failures — expired tokens, bad credentials, and missing scopes.

Related errors

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

Appendix: source

Thrown at src/Aspire.Hosting.RemoteHost/JsonRpcAuthenticationState.cs:67

            if (isMatch)
            {
                IsAuthenticated = true;
            }

            return isMatch;
        }
        finally
        {
            CryptographicOperations.ZeroMemory(providedTokenBytes);
        }
    }

    public void ThrowIfNotAuthenticated()
    {
        if (!IsAuthenticated)
        {
            throw new InvalidOperationException("Client must authenticate before invoking AppHost RPC methods.");
        }
    }
}

View on GitHub (pinned to 25830f84bd)