NousResearch/hermes-agent · error · Error

Remote gateway session token is required.

Error message

Remote gateway session token is required.

What it means

Thrown by buildRemoteBlock, the constructor for a {url, authMode, token} remote connection block. Only OAuth-auth remotes are exempt from carrying a token (they authenticate via the login-window session cookie verified at connect time in resolveRemoteBackend); for any other authMode, decryptDesktopSecret(token) must yield a value. A token that fails to decrypt — or was never saved — triggers this.

Source

Thrown at apps/desktop/electron/main.ts:7014

    sshPort: (ssh || savedSsh)?.port || null,
    sshKeyPath: (ssh || savedSsh)?.keyPath || '',
    sshRemoteHermesPath: (ssh || savedSsh)?.remoteHermesPath || '',
    sshRemoteProfile: (ssh || savedSsh)?.remoteProfile || '',
    // The env override only forces the global/primary connection; a per-profile
    // scope is never overridden by HERMES_DESKTOP_REMOTE_URL.
    envOverride
  }
}

// Build + validate a `{ url, authMode, token }` remote block. OAuth gateways
// authenticate via the login-window session cookie (verified at connect time in
// resolveRemoteBackend), so only token-auth remotes require a saved token.
// `org` (optional) is the Hermes Cloud org slug/id the instance was discovered
// under — persisted so Settings can reopen into the same org; omitted from the
// block when empty so plain remote connections stay unchanged.
function buildRemoteBlock(remoteUrl, authMode, token, org?: string) {
  if (authMode !== 'oauth' && !decryptDesktopSecret(token)) {
    throw new Error('Remote gateway session token is required.')
  }

  const block: { url: string; authMode: string; token: object; org?: string } = {
    url: normalizeRemoteBaseUrl(remoteUrl),
    authMode,
    token
  }

  const orgValue = typeof org === 'string' ? org.trim() : ''

  if (orgValue) {
    block.org = orgValue
  }

  return block
}

function coerceDesktopConnectionConfig(input: any = {}, existing = readDesktopConnectionConfig(), options: any = {}) {

View on GitHub (pinned to c896c09c42)

Solutions

1. Enter and save a non-empty session token in Settings → Gateway when using token auth.
2. Switch the remote's authMode to 'oauth' if the gateway supports cookie-based login — then no static token is required.
3. If a previously saved token stopped decrypting (keyring reset), clear and re-save it.

function hasRemoteToken(authMode, token) {
  if (authMode === 'oauth') return true // cookie-authed at connect time
  return Boolean(decryptDesktopSecret(token))
}
if (!hasRemoteToken(authMode, token)) {
  requireTokenInput()
}

function isTokenAuthReady(authMode, token) {
  return authMode === 'oauth' || Boolean(decryptDesktopSecret(token))
}

When it happens

Trigger: Saving a token-mode remote connection with an empty token; a previously-saved token whose stored encoding can no longer be decrypted (keyring changed/re-encrypted); passing token as a raw string when decryptDesktopSecret expects the stored secret envelope.

Common situations: Settings → Gateway saved with the token field left blank while authMode is 'token'; OS keyring reset losing previously-encrypted tokens; migrating configs between machines.

Related errors

• Remote Hermes gateway is selected, but no session token is s
• HERMES_DESKTOP_REMOTE_URL is set but HERMES_DESKTOP_REMOTE_T
• Gateway token response missing access_token
• Gateway did not return a WS ticket.
• SSH host is required.

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