chenhg5/cc-connect · error

incomplete onboarding response

Error message

incomplete onboarding response

What it means

Thrown after a successful 'begin' response when the onboarding payload is structurally incomplete: either DeviceCode or VerificationURIComplete is empty. The flow cannot poll or show the QR URL without both, so it fails fast instead of hanging until timeout.

Source

Thrown at cmd/cc-connect/feishu.go:568

	}
	if len(initRes.SupportedAuthMethods) > 0 && !containsString(initRes.SupportedAuthMethods, "client_secret") {
		return nil, fmt.Errorf("current environment does not support client_secret auth")
	}

	var beginRes registrationBeginResponse
	beginParams := map[string]string{
		"archetype":         "PersonalAgent",
		"auth_method":       "client_secret",
		"request_user_info": "open_id",
	}
	if err := client.registrationCall("begin", beginParams, &beginRes); err != nil {
		return nil, fmt.Errorf("begin failed: %w", err)
	}
	if beginRes.Error != "" {
		return nil, fmt.Errorf("%s: %s", beginRes.Error, beginRes.ErrorDescription)
	}
	if beginRes.DeviceCode == "" || beginRes.VerificationURIComplete == "" {
		return nil, fmt.Errorf("incomplete onboarding response")
	}

	fmt.Println("请使用飞书/Lark 手机 App 扫码完成机器人创建与授权：")
	fmt.Printf("URL: %s\n\n", beginRes.VerificationURIComplete)
	tryPrintTerminalQRCode(beginRes.VerificationURIComplete)
	if opts.QRImagePath != "" {
		if err := saveQRCodeImage(beginRes.VerificationURIComplete, opts.QRImagePath); err != nil {
			fmt.Fprintf(os.Stderr, "Warning: failed to save QR image: %v\n", err)
		} else {
			fmt.Printf("QR code saved to: %s\n\n", opts.QRImagePath)
		}
	}

	interval := beginRes.Interval
	if interval <= 0 {
		interval = 5
	}
	expireIn := beginRes.ExpireIn

View on GitHub (pinned to 4000b2338a)

Solutions

1. Run with debug output enabled and inspect the raw begin response body to see which fields actually came back.
2. Re-run setup — a transient server-side glitch can produce an empty payload.
3. Verify you are hitting the correct, current registration endpoint (feishu vs lark baseURL); a wrong endpoint may return an empty object.
4. If fields were renamed server-side, upgrade cc-connect so the registrationBeginResponse struct matches the current API.

Example fix

// before
// server returns {"status":"ok"} with no device_code
// after
// check debug: registration action=begin status=200 body={"device_code":"dc_...","verification_uri_complete":"https://..."}
// re-run against correct endpoint:
$ cc-connect setup feishu --debug

// validate the begin response before proceeding
type beginResp struct {
	DeviceCode              string `json:"device_code"`
	VerificationURIComplete string `json:"verification_uri_complete"`
}
if beginRes.DeviceCode == "" || beginRes.VerificationURIComplete == "" {
	// inspect raw body / re-request before entering the poll loop
}

func validBegin(r *registrationBeginResponse) bool {
	return r != nil && r.DeviceCode != "" && r.VerificationURIComplete != ""
}

When it happens

Trigger: The begin response decodes but omits device_code and/or verification_uri_complete — e.g. the server returned a 2xx body with an empty/partial payload, or a contract change renamed the fields so they deserialize to zero values.

Common situations: Registration API version drift (field renamed/moved); a proxy or captive portal returning a truncated/empty 200 body; hitting the wrong endpoint that returns an empty JSON object.

Understand the failure class

Background: "invalid response format", "malformed payload", "missing data field": when an API returns 200 but the response shape is wrong — this error's family across 23 libraries.

Related errors

• codex app-server turn/start returned empty turn id
• init failed: %w
• %s: %s
• current environment does not support client_secret auth
• begin failed: %w

AI-assisted analysis of chenhg5/cc-connect@4000b2338a (2026-09-06). Data as JSON: /api/errors/c8c3603f9c61f441. Report an issue: GitHub.