microsoft/aspire · error · Error

ASPIRE_REMOTE_APPHOST_TOKEN environment variable is not set.

Error message

ASPIRE_REMOTE_APPHOST_TOKEN environment variable is not set.

What it means

During AspireClient.connect, before authenticating, the client reads ASPIRE_REMOTE_APPHOST_TOKEN from the environment. If it is missing, connect throws immediately instead of attempting an unauthenticated JSON-RPC handshake.

Solutions

Set ASPIRE_REMOTE_APPHOST_TOKEN before starting the process, e.g. `ASPIRE_REMOTE_APPHOST_TOKEN=<token> node app.mts`.
Run the client through the Aspire AppHost / launch environment that injects the token automatically.
Add the token to your .env / CI secret configuration and ensure it is loaded (dotenv, workflow env mapping).
Verify the exact spelling ASPIRE_REMOTE_APPHOST_TOKEN (check `printenv | grep ASPIRE`).

Example fix

// before
const client = new AspireClient();
await client.connect(); // throws: token missing

// after
// shell: export ASPIRE_REMOTE_APPHOST_TOKEN=<token>
if (!process.env.ASPIRE_REMOTE_APPHOST_TOKEN) {
  throw new Error('Set ASPIRE_REMOTE_APPHOST_TOKEN before connecting');
}
const client = new AspireClient();
await client.connect();

Defensive patterns

Strategy: validation

Validate before calling

if (!process.env.ASPIRE_REMOTE_APPHOST_TOKEN) {
  throw new Error('Set ASPIRE_REMOTE_APPHOST_TOKEN before calling connect()');
}

Try / catch

try {
  await client.connect();
} catch (err) {
  if (String(err.message).includes('ASPIRE_REMOTE_APPHOST_TOKEN')) {
    console.error('Missing token: run via the Aspire AppHost or export the variable');
  }
  throw err;
}

Prevention

Launch the client through the Aspire environment that injects the token.
Check for the variable at process start with a fast-fail guard.
In CI, wire the token as a secret env mapping.
Grep for typos: ASPIRE_REMOTE_APPHOST_TOKEN exactly.

When it happens

Trigger: Calling connect() (which opens the socket and starts the authenticate handshake) in a process where the ASPIRE_REMOTE_APPHOST_TOKEN environment variable was never set.

Common situations: Running the generated client outside the Aspire launch environment (plain node script, IDE run without env vars); CI job without the secret injected; token set only in one shell profile but the app launched from another; typo in variable name.

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

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

Appendix: source

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

                        if (!callback) {
                            throw new Error(`Callback not found: ${callbackId}`);
                        }
                        try {
                            // The registered wrapper handles arg unpacking and handle wrapping
                            // Pass this client so handles can be wrapped with typed wrapper classes
                            return await Promise.resolve(callback(args, this));
                        } catch (error) {
                            const message = error instanceof Error ? error.message : String(error);
                            throw new Error(`Callback execution failed: ${message}`);
                        }
                    });

                    socket.on('error', onConnectedSocketError);
                    socket.on('close', onConnectedSocketClose);

                    const authToken = process.env.ASPIRE_REMOTE_APPHOST_TOKEN;
                    if (!authToken) {
                        throw new Error('ASPIRE_REMOTE_APPHOST_TOKEN environment variable is not set.');
                    }
                    this.connection.listen();
                    const authenticated = await this.connection.sendRequest<boolean>('authenticate', authToken);
                    if (!authenticated) {
                        throw new Error('Failed to authenticate to the AppHost server.');
                    }

                    connectedClients.add(this);
                    this._connectPromise = null;
                    settled = true;

                    resolve();
                } catch (error) {
                    failConnect(error instanceof Error ? error : new Error(String(error)));
                }
            };

            const timeout = setTimeout(() => {

View on GitHub (pinned to 25830f84bd)