{"record":{"id":"c8c3603f9c61f441","repo":"chenhg5/cc-connect","slug":"incomplete-onboarding-response","errorCode":null,"errorMessage":"incomplete onboarding response","messagePattern":"incomplete onboarding response","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cmd/cc-connect/feishu.go","lineNumber":568,"sourceCode":"\t}\n\tif len(initRes.SupportedAuthMethods) > 0 && !containsString(initRes.SupportedAuthMethods, \"client_secret\") {\n\t\treturn nil, fmt.Errorf(\"current environment does not support client_secret auth\")\n\t}\n\n\tvar beginRes registrationBeginResponse\n\tbeginParams := map[string]string{\n\t\t\"archetype\":         \"PersonalAgent\",\n\t\t\"auth_method\":       \"client_secret\",\n\t\t\"request_user_info\": \"open_id\",\n\t}\n\tif err := client.registrationCall(\"begin\", beginParams, &beginRes); err != nil {\n\t\treturn nil, fmt.Errorf(\"begin failed: %w\", err)\n\t}\n\tif beginRes.Error != \"\" {\n\t\treturn nil, fmt.Errorf(\"%s: %s\", beginRes.Error, beginRes.ErrorDescription)\n\t}\n\tif beginRes.DeviceCode == \"\" || beginRes.VerificationURIComplete == \"\" {\n\t\treturn nil, fmt.Errorf(\"incomplete onboarding response\")\n\t}\n\n\tfmt.Println(\"请使用飞书/Lark 手机 App 扫码完成机器人创建与授权：\")\n\tfmt.Printf(\"URL: %s\\n\\n\", beginRes.VerificationURIComplete)\n\ttryPrintTerminalQRCode(beginRes.VerificationURIComplete)\n\tif opts.QRImagePath != \"\" {\n\t\tif err := saveQRCodeImage(beginRes.VerificationURIComplete, opts.QRImagePath); err != nil {\n\t\t\tfmt.Fprintf(os.Stderr, \"Warning: failed to save QR image: %v\\n\", err)\n\t\t} else {\n\t\t\tfmt.Printf(\"QR code saved to: %s\\n\\n\", opts.QRImagePath)\n\t\t}\n\t}\n\n\tinterval := beginRes.Interval\n\tif interval <= 0 {\n\t\tinterval = 5\n\t}\n\texpireIn := beginRes.ExpireIn","sourceCodeStart":550,"sourceCodeEnd":586,"githubUrl":"https://github.com/chenhg5/cc-connect/blob/4000b2338aa6e850c99df54f8b0ed6ed7460b401/cmd/cc-connect/feishu.go#L550-L586","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Run with debug output enabled and inspect the raw begin response body to see which fields actually came back.","Re-run setup — a transient server-side glitch can produce an empty payload.","Verify you are hitting the correct, current registration endpoint (feishu vs lark baseURL); a wrong endpoint may return an empty object.","If fields were renamed server-side, upgrade cc-connect so the registrationBeginResponse struct matches the current API."],"exampleFix":"// before\n// server returns {\"status\":\"ok\"} with no device_code\n// after\n// check debug: registration action=begin status=200 body={\"device_code\":\"dc_...\",\"verification_uri_complete\":\"https://...\"}\n// re-run against correct endpoint:\n$ cc-connect setup feishu --debug","handlingStrategy":"validation","validationCode":"// validate the begin response before proceeding\ntype beginResp struct {\n\tDeviceCode              string `json:\"device_code\"`\n\tVerificationURIComplete string `json:\"verification_uri_complete\"`\n}\nif beginRes.DeviceCode == \"\" || beginRes.VerificationURIComplete == \"\" {\n\t// inspect raw body / re-request before entering the poll loop\n}","typeGuard":"func validBegin(r *registrationBeginResponse) bool {\n\treturn r != nil && r.DeviceCode != \"\" && r.VerificationURIComplete != \"\"\n}","tryCatchPattern":null,"preventionTips":["Enable debug logging to capture raw response bodies during setup.","Confirm the correct regional endpoint before starting onboarding.","Fail fast on empty payloads instead of polling a dead session."],"tags":["feishu","registration","protocol","empty-response"],"backgroundTag":"unexpected-api-response-shape","analyzedSha":"4000b2338aa6e850c99df54f8b0ed6ed7460b401","analyzedAt":"2026-09-06T11:45:09.575Z","contentChangedAt":"2026-09-06T11:45:09.575Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}