What causes "Could not refresh the remote gateway WebSocket ticket." in NousResearch/hermes-agent?

Retry after confirming the remote gateway is up and reachable (its health/status route).

Could not refresh the remote gateway WebSocket ticket.

Error message

Could not refresh the remote gateway WebSocket ticket.

What it means

The generic failure thrown by resolveGatewayWsUrl when ticket minting completed without ok, without needsOauthLogin, and the backend supplied no error string — i.e. the mint endpoint answered, but the response was an unrecognized failure shape. It is the last-resort branch for OAuth ticket refresh when nothing more specific applies.

Source

Thrown at apps/shared/src/websocket-url.ts:66

    try {
      const result = await mint(profile)

      if (typeof result === 'string') {
        return result
      }

      if (result.ok) {
        return result.wsUrl
      }

      if (result.needsOauthLogin) {
        throw new GatewayReauthRequiredError(
          'Your remote gateway session has expired. Open Settings -> Gateway and click "Sign in" again.',
          { cause: new Error(result.error) }
        )
      }

      throw new Error(result.error || 'Could not refresh the remote gateway WebSocket ticket.')
    } catch (error) {
      if (isGatewayReauthRequired(error)) {
        throw error instanceof GatewayReauthRequiredError
          ? error
          : new GatewayReauthRequiredError(
              'Your remote gateway session has expired. Open Settings -> Gateway and click "Sign in" again.',
              { cause: error }
            )
      }

      throw error
    }
  }

  if (mint) {
    const fresh = await mint(profile).catch(() => null)

    if (typeof fresh === 'string') {

View on GitHub (pinned to c896c09c42)

Solutions

Retry after confirming the remote gateway is up and reachable (its health/status route).
Check gateway logs for the ticket-mint request and its failure reason — the empty error hides it server-side.
Update both Desktop app and gateway to matching versions if the ticket response shape changed.

Defensive patterns

Strategy: retry

Try / catch

try {
  await resolveGatewayWsUrl(deps, conn)
} catch (e) {
  if (isGatewayReauthRequiredError(e)) throw e
  if (e instanceof Error && e.message.includes('Could not refresh')) {
    await backoffRetry(2) // transient backend/proxy hiccup
  } else throw e
}

Prevention

Distinguish this generic failure from reauth-required before retrying or prompting.
Log the raw mint response body when it has no error field — the cause is server-side.
Version-align app and gateway so ticket response shapes stay compatible.

When it happens

Trigger: getGatewayWsUrl returns { ok: false } with an empty/missing error field — backend ticket endpoint down or returning an unexpected body, or a shape change in the ticket API between app and backend versions.

Common situations: Remote gateway mid-restart when the ticket route is unavailable, reverse proxy returning HTML that got parsed into an empty failure, or version drift between apps/shared and the gateway's ticket endpoint.

Related errors

AI-assisted analysis of NousResearch/hermes-agent@c896c09c42 (2026-08-14). Data as JSON: /api/errors/a959414910f4c769. Report an issue: GitHub.