{"record":{"id":"e399c7e25f05a18f","repo":"microsoft/aspire","slug":"failed-to-authenticate-to-the-apphost-server-transport","errorCode":null,"errorMessage":"Failed to authenticate to the AppHost server.","messagePattern":"Failed to authenticate to the AppHost server\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"src/Aspire.Hosting.CodeGeneration.TypeScript/Resources/transport.mts","lineNumber":970,"sourceCode":"                            // Pass this client so handles can be wrapped with typed wrapper classes\n                            return await Promise.resolve(callback(args, this));\n                        } catch (error) {\n                            const message = error instanceof Error ? error.message : String(error);\n                            throw new Error(`Callback execution failed: ${message}`);\n                        }\n                    });\n\n                    socket.on('error', onConnectedSocketError);\n                    socket.on('close', onConnectedSocketClose);\n\n                    const authToken = process.env.ASPIRE_REMOTE_APPHOST_TOKEN;\n                    if (!authToken) {\n                        throw new Error('ASPIRE_REMOTE_APPHOST_TOKEN environment variable is not set.');\n                    }\n                    this.connection.listen();\n                    const authenticated = await this.connection.sendRequest<boolean>('authenticate', authToken);\n                    if (!authenticated) {\n                        throw new Error('Failed to authenticate to the AppHost server.');\n                    }\n\n                    connectedClients.add(this);\n                    this._connectPromise = null;\n                    settled = true;\n\n                    resolve();\n                } catch (error) {\n                    failConnect(error instanceof Error ? error : new Error(String(error)));\n                }\n            };\n\n            const timeout = setTimeout(() => {\n                failConnect(new Error('Connection timeout'));\n            }, timeoutMs);\n\n            socket.once('error', onPendingError);\n            socket.once('close', onPendingClose);","sourceCodeStart":952,"sourceCodeEnd":988,"githubUrl":"https://github.com/microsoft/aspire/blob/25830f84bd145686607ad00c057b3f84e2e51d43/src/Aspire.Hosting.CodeGeneration.TypeScript/Resources/transport.mts#L952-L988","documentation":"After sending the JSON-RPC 'authenticate' request with the ASPIRE_REMOTE_APPHOST_TOKEN value, the client checks the boolean result; a false response means the server rejected the credentials, and connect throws this generic authentication-failure error.","triggerScenarios":"Calling connect() where the server-side 'authenticate' handler returns false: token value does not match the AppHost's expected token, stale/rotated token, whitespace or encoding differences, or server-side auth state rejecting the session.","commonSituations":"Token copied from an old AppHost run (regenerated each run); environment variable value with trailing newline/quotes; connecting to a different AppHost instance than the token belongs to; server-side changed auth requirements after an upgrade.","solutions":["Get a fresh token from the currently running AppHost (it is regenerated per run) and set it as ASPIRE_REMOTE_APPHOST_TOKEN.","Check the AppHost/server logs for the authentication rejection reason.","Verify the env value has no surrounding quotes, whitespace, or truncation (compare token lengths).","Confirm you are connecting to the intended AppHost endpoint/port that issued the token."],"exampleFix":"// before\n# shell\nexport ASPIRE_REMOTE_APPHOST_TOKEN='old-token-from-previous-run'\n\n// after\nexport ASPIRE_REMOTE_APPHOST_TOKEN='<token printed by the CURRENT AppHost run>'\nawait client.connect(); // authenticates","handlingStrategy":"retry","validationCode":"const token = process.env.ASPIRE_REMOTE_APPHOST_TOKEN;\nif (!token || token.length < 16 || /\\s/.test(token)) {\n  console.warn('token looks stale or malformed; fetch a fresh one from the current AppHost run');\n}","typeGuard":null,"tryCatchPattern":"try {\n  await client.connect();\n} catch (err) {\n  if (String(err.message) === 'Failed to authenticate to the AppHost server.') {\n    console.error('Token rejected — get a fresh token from the running AppHost');\n  }\n  throw err;\n}","preventionTips":["Always take the token from the current AppHost run, never a cached one.","Trim quotes/whitespace when copying tokens into env config.","Confirm endpoint and token come from the same AppHost instance.","Check server auth logs on rejection."],"tags":["authentication","token","json-rpc","typescript"],"backgroundTag":"authentication-failed","analyzedSha":"25830f84bd145686607ad00c057b3f84e2e51d43","analyzedAt":"2026-09-16T11:10:06.193Z","contentChangedAt":"2026-09-16T11:10:06.193Z","schemaVersion":2},"datasetVersion":"2026-09-21T04:17:39.646Z"}