CherryHQ/cherry-studio · error · Error

QQ Bot AppID and ClientSecret are required

Error message

QQ Bot AppID and ClientSecret are required

What it means

Thrown by QqAdapter.performConnect() when appId or clientSecret is empty. It is the connect-time guard mirroring checkReady(); performConnect refuses to start the gateway if credentials are missing.

Source

Thrown at src/main/ai/channels/adapters/qq/QqAdapter.ts:140

  private readonly DEDUP_MAX_ENTRIES = 500

  constructor(config: ChannelAdapterConfig<'qq'>) {
    super(config)
    const { app_id, client_secret, allowed_chat_ids, mention_only } = config.channelConfig
    this.appId = app_id
    this.clientSecret = client_secret
    this.allowedChatIds = allowed_chat_ids ?? []
    this.notifyChatIds = [...this.allowedChatIds]
    this.mentionOnly = mention_only ?? true
  }

  protected override async checkReady(): Promise<boolean> {
    return !!(this.appId && this.clientSecret)
  }

  protected override async performConnect(_signal: AbortSignal): Promise<void> {
    if (!this.appId || !this.clientSecret) {
      throw new Error('QQ Bot AppID and ClientSecret are required')
    }

    this.shouldStop = false
    await this.startGateway()

    this.log.info('QQ bot started')
  }

  protected override async performDisconnect(): Promise<void> {
    this.shouldStop = true
    this.cleanup()
    this.log.info('QQ bot stopped')
  }

  private async getAccessToken(): Promise<string> {
    // Check cache
    if (this.tokenCache && Date.now() < this.tokenCache.expiresAt - 60000) {
      return this.tokenCache.accessToken

View on GitHub (pinned to 726446b54c)

Solutions

1. Obtain AppID and ClientSecret from the QQ Bot console (https://q.qq.com) and fill them in the channel config.
2. Trim whitespace when reading config; validate non-empty before allowing connect.
3. Rely on checkReady() to keep the adapter 'not ready' (grey) until credentials are present, preventing performConnect from firing.

// Validate before allowing connect.
function qqCredentialsPresent(cfg: QqChannelConfig): boolean {
  return Boolean(cfg.app_id?.trim() && cfg.client_secret?.trim())
}

function isQqMissingCredentials(e: unknown): e is Error {
  return e instanceof Error && e.message === 'QQ Bot AppID and ClientSecret are required'
}

if (!qqCredentialsPresent(cfg)) { showConfigError('Enter QQ AppID and ClientSecret'); return }
try { await qq.connect() } catch (e) {
  if (isQqMissingCredentials(e)) { showConfigError('Enter QQ AppID and ClientSecret'); return }
  throw e
}

When it happens

Trigger: Channel config loaded with empty/undefined app_id or client_secret; performConnect runs before credentials are supplied and throws before startGateway().

Common situations: User created the QQ channel but didn't fill in the AppID/ClientSecret from q.qq.com, env/config load order delivered empty strings, or a paste with stray whitespace.

Related errors

• Slack bot token (xoxb-...) is required
• Private key must be a non-empty string
• Cherry Assistant package configuration is invalid: ${invalid
• Discord bot token is required
• Feishu WebSocket connection failed: ${error instanceof Error

AI-assisted analysis of CherryHQ/cherry-studio@726446b54c (2026-08-12). Data as JSON: /api/errors/d350eb5176de895f. Report an issue: GitHub.