slopus/happy · error

No main session key from gateway

Error message

No main session key from gateway

What it means

After connecting to the OpenClaw gateway, startSession() asks the socket for the main session key. The gateway is expected to assign this key during the connection handshake; if getMainSessionKey() returns nothing, happy cannot identify the session and throws. This indicates a protocol-level problem with the gateway connection rather than a local configuration issue.

Source

Thrown at packages/happy-cli/src/openclaw/OpenClawBackend.ts:106

    });

    this.socket.onEvent((event, payload) => {
      this.handleEvent(event, payload);
    });
  }

  async startSession(): Promise<StartSessionResult> {
    this.connectionReady = new Promise<void>((resolve, reject) => {
      this.connectionResolve = resolve;
      this.connectionReject = reject;
    });

    this.socket.connect(this.gatewayConfig);
    await this.connectionReady;

    this.sessionKey = this.socket.getMainSessionKey();
    if (!this.sessionKey) {
      throw new Error('No main session key from gateway');
    }

    const sessionId = this.sessionKey;
    this.log(`Session started: ${sessionId}`);
    return { sessionId };
  }

  async sendPrompt(sessionId: SessionId, prompt: string): Promise<void> {
    if (!this.socket.isConnected()) {
      throw new Error('Not connected to OpenClaw gateway');
    }

    this.lastDeltaText = null;

    this.turnReady = new Promise<void>((resolve, reject) => {
      this.turnResolve = resolve;
      this.turnReject = reject;
    });

View on GitHub (pinned to b824cd0a46)

Solutions

1. Verify the gateway version matches what the happy CLI expects (update both openclaw and happy)
2. Check gateway logs to confirm it sends the main session key during the connection handshake
3. Restart the gateway and retry; test against a known-good local openclaw instance

await backend.start(); // then
const key = socket.getMainSessionKey();
if (!key) throw new Error('Gateway did not provide a main session key');

const hasSessionKey = (k: string | null | undefined): k is string => typeof k === 'string' && k.length > 0;

try {
  const { sessionId } = await backend.startSession();
} catch (err) {
  if (err.message === 'No main session key from gateway') {
    await backend.restart(); // reconnect and re-handshake
  } else throw err;
}

When it happens

Trigger: OpenClawBackend.startSession() calls this.socket.getMainSessionKey() after `await this.connectionReady` and the return value is falsy — the gateway never provided a main session key.

Common situations: Connecting to an incompatible or non-standard gateway implementation that omits the main session key in its handshake; gateway version mismatch with the protocol happy expects; gateway crashed mid-handshake while connectionReady still resolved.

Related errors

• Not connected to OpenClaw gateway
• OpenClaw gateway not found. Either: - Install and run open
• Session not started
• ACP session is not started
• Metadata version mismatch

AI-assisted analysis of slopus/happy@b824cd0a46 (2026-08-31). Data as JSON: /api/errors/b7618ef25ecda340. Report an issue: GitHub.