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.

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

• begin failed
• codex app-server turn/start returned empty turn id
• current environment does not support client_secret auth
• first-chunk: 206 without parseable Content-Range
• init failed

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

Appendix: 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)