chenhg5/cc-connect · error

begin failed

Error message

begin failed: %w

What it means

This error wraps any transport/HTTP failure from the registration service's 'begin' call, which starts the device-code (QR) onboarding session. The %w wrap preserves the underlying cause (network error, non-2xx status, etc.). It means the onboarding session could not even be created.

Solutions

1. Check network connectivity to the registration endpoint (try curl to the baseURL) and any proxy settings.
2. Re-run the setup command — transient network blips are the most common cause.
3. Verify the configured/derived baseURL for the registration client is correct (feishu vs lark endpoints).
4. Check Feishu/Lark open-platform status for outages; inspect debug logs (registration debug output) for the exact HTTP failure.

Example fix

// before
$ cc-connect setup feishu   # fails behind corporate proxy
// after
$ export HTTPS_PROXY=http://proxy.corp.local:8080
$ cc-connect setup feishu

// preflight connectivity
resp, err := http.Get(registrationBaseURL + "/health")
if err != nil { log.Fatal("registration endpoint unreachable: ", err) }
resp.Body.Close()

if err := runRegistrationFlow(...); err != nil {
	if errors.Is(err, context.DeadlineExceeded) || isNetErr(err) {
		// exponential backoff retry
	}
	return fmt.Errorf("feishu setup: %w", err)
}

When it happens

Trigger: client.registrationCall("begin", beginParams, &beginRes) returns a non-nil error — e.g. the HTTP POST to the registration endpoint fails, times out, or the server returns an unexpected status handled inside registrationCall.

Common situations: No internet connectivity or blocked network during `cc-connect` Feishu setup; corporate proxy/firewall blocking the accounts endpoint; registration service outage or maintenance; misconfigured baseURL pointing at a non-existent host.

Understand the failure class

Background: "API request failed": what wrapped HTTP errors from external APIs mean and how to find the real cause — this error's family across 29 libraries.

Related errors

• init failed
• cloud_web: register request
• first-chunk request
• poll failed
• range request

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

Appendix: source

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

	var initRes registrationInitResponse
	if err := client.registrationCall("init", nil, &initRes); err != nil {
		return nil, fmt.Errorf("init failed: %w", err)
	}
	if initRes.Error != "" {
		return nil, fmt.Errorf("%s: %s", initRes.Error, initRes.ErrorDescription)
	}
	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)
		}
	}

View on GitHub (pinned to 4000b2338a)