CherryHQ/cherry-studio · error · Error

Feishu registration begin failed: ${JSON.stringify(res)}

Error message

Feishu registration begin failed: ${JSON.stringify(res)}

What it means

Thrown by registrationBegin() when the 'begin' action response lacks device_code or verification_uri_complete. These two fields are required to drive the device/QR flow; their absence means the device-flow start did not actually begin.

Source

Thrown at src/main/ai/channels/adapters/feishu/FeishuAppRegistration.ts:74

  const baseUrl = BASE_URLS[domain]

  // Step 1: init — check supported auth methods
  const initRes = await postRegistration(baseUrl, { action: 'init' })
  logger.info('Feishu registration init response', { supported: initRes })

  // Step 2: begin — start device flow
  const res = await postRegistration(baseUrl, {
    action: 'begin',
    archetype: 'PersonalAgent',
    auth_method: 'client_secret',
    request_user_info: 'open_id'
  })

  const deviceCode = res.device_code as string | undefined
  const verificationUri = res.verification_uri_complete as string | undefined

  if (!deviceCode || !verificationUri) {
    throw new Error(`Feishu registration begin failed: ${JSON.stringify(res)}`)
  }

  return {
    deviceCode,
    verificationUri,
    interval: (res.interval as number) ?? 5,
    expiresIn: (res.expires_in as number) ?? 600
  }
}

export async function registrationPoll(
  domain: FeishuDomain,
  deviceCode: string,
  options: { interval: number; expiresIn: number; signal?: AbortSignal }
): Promise<RegistrationResult> {
  const baseUrl = BASE_URLS[domain]
  const deadline = Date.now() + options.expiresIn * 1000
  let interval = options.interval * 1000

View on GitHub (pinned to 726446b54c)

Solutions

1. Inspect the embedded JSON — look for an error/error_description field that explains the rejection.
2. Confirm archetype:'PersonalAgent' and auth_method:'client_secret' are still the accepted values for the target domain.
3. Verify the chosen FeishuDomain has a working registration endpoint (BASE_URLS entry).
4. Retry once; if the schema change is real, update the field extraction to match the new response.

// Validate the begin response shape before relying on it.
function hasDeviceFlowFields(res: unknown): res is { device_code: string; verification_uri_complete: string } {
  return typeof res === 'object' && res !== null
    && typeof (res as any).device_code === 'string'
    && typeof (res as any).verification_uri_complete === 'string'
}

function isFeishuBeginFailed(e: unknown): e is Error {
  return e instanceof Error && e.message.startsWith('Feishu registration begin failed:')
}

try {
  const { deviceCode, verificationUri } = await registrationBegin(domain)
  showQr(verificationUri)
} catch (e) {
  if (isFeishuBeginFailed(e)) { notifyUser('Could not start Feishu registration; retry later'); return }
  throw e
}

When it happens

Trigger: postRegistration with action:'begin', archetype:'PersonalAgent', auth_method:'client_secret' returns a JSON object missing device_code and/or verification_uri_complete. The full response is JSON.stringify-d into the message.

Common situations: Feishu changed the device-flow response schema, the archetype/auth_method values are rejected, the registration endpoint returned an inline error object instead of throwing, or the domain's API surface doesn't support this flow.

Related errors

• Feishu registration poll error: ${error}
• Feishu app registration timed out
• Cherry Assistant package configuration is invalid: ${invalid
• Invalid JSON from Feishu registration API: ${text.slice(0, 2
• Registration polling aborted

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