chenhg5/cc-connect · error

begin failed: %w

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.

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)

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: %w
• poll failed: %w
• cloud_web: register request: %w
• remote image HTTP status %d
• first-chunk request: %w

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