{"record":{"id":"66ae6c7accbba8bc","repo":"larksuite/cli","slug":"invalid-v0-2-index-w","errorCode":null,"errorMessage":"invalid v0.2 index: %w","messagePattern":"invalid v0\\.2 index: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/skillscheck/sync.go","lineNumber":356,"sourceCode":"\t\t\tAction: \"failed\",\n\t\t\tLayout: targetLayout,\n\t\t\tErr:    fmt.Errorf(\"suite skills sync failed: %s\", strings.Join(reasons, \"; \")),\n\t\t\tDetail: strings.Join(reasons, \"\\n\"),\n\t\t\tForce:  opts.Force,\n\t\t}\n\t}\n\n\treturn fallbackSeparate(opts, previous, readable, localOfficial, installed, fallbackPlan, reasons)\n}\n\nfunc fetchOfficialSkills(runner SkillsRunner, source string) ([]string, error) {\n\tresult := runner.FetchSkillsIndex(source)\n\tif result == nil || result.Err != nil {\n\t\treturn nil, fmt.Errorf(\"index request failed: %s\", resultDetail(result))\n\t}\n\tofficial, err := ParseOfficialSkillsIndexJSON(result.Stdout.String())\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"invalid v0.2 index: %w\", err)\n\t}\n\tif len(official) == 0 {\n\t\treturn nil, fmt.Errorf(\"v0.2 index contains no skills\")\n\t}\n\treturn official, nil\n}\n\nfunc listInstalledSkills(runner SkillsRunner) ([]installedSkill, error) {\n\tjsonResult := runner.ListGlobalSkillsJSON()\n\tif jsonResult != nil && jsonResult.Err == nil {\n\t\tif installed, err := parseInstalledSkillsJSON(jsonResult.Stdout.String()); err == nil {\n\t\t\treturn installed, nil\n\t\t}\n\t}\n\n\ttextResult := runner.ListGlobalSkills()\n\tif textResult != nil && textResult.Err == nil {\n\t\tnames := ParseSkillsList(textResult.Stdout.String())","sourceCodeStart":338,"sourceCodeEnd":374,"githubUrl":"https://github.com/larksuite/cli/blob/7fd6ef3c07182257ce776cdc5a614e122d5bd4b3/internal/skillscheck/sync.go#L338-L374","documentation":"fetchOfficialSkills parses the fetched index body with ParseOfficialSkillsIndexJSON; when that fails it wraps the parse error with this message. The remote responded, but its stdout is not a valid v0.2 skills index JSON (wrong shape, missing fields, HTML error page, truncation). The wrapped cause (%w) carries the precise JSON/field error.","triggerScenarios":"SyncSkills -> fetchOfficialSkills where ParseOfficialSkillsIndexJSON(result.Stdout.String()) returns a non-nil error.","commonSituations":"The endpoint returned an HTML login/error page instead of JSON; the server publishes a newer or older index schema than v0.2; the response was truncated or proxied/rewritten; a captive portal intercepted the request; wrong URL pointing at a non-index resource.","solutions":["Curl the source URL and inspect the body — confirm it is the expected v0.2 index JSON","Check the wrapped cause (errors.Unwrap) for the exact JSON field that failed","Verify you are hitting the correct, current index URL for the CLI version; update the CLI if the schema changed","Rule out proxy/captive-portal interference that injects HTML into the response","Pin or correct SkillsSources() to a source that serves the v0.2 schema"],"exampleFix":"// before: treating body blindly\nofficial, err := ParseOfficialSkillsIndexJSON(result.Stdout.String())\n// after: diagnose the body when parse fails\nofficial, err := ParseOfficialSkillsIndexJSON(result.Stdout.String())\nif err != nil {\n    log.Printf(\"index body head: %.200s\", result.Stdout.String())\n    return nil, fmt.Errorf(\"invalid v0.2 index: %w\", err)\n}","handlingStrategy":"validation","validationCode":"body := result.Stdout.String()\nif !strings.HasPrefix(strings.TrimSpace(body), \"{\") {\n    return errors.New(\"index endpoint did not return JSON (likely HTML error page)\")\n}\nvar probe map[string]any\nif json.Unmarshal([]byte(body), &probe) != nil {\n    return errors.New(\"index body is not valid JSON\")\n}","typeGuard":"func looksLikeV02Index(body string) bool {\n    var idx struct {\n        Skills []map[string]any `json:\"skills\"`\n    }\n    return json.Unmarshal([]byte(body), &idx) == nil && idx.Skills != nil\n}","tryCatchPattern":"official, err := fetchOfficialSkills(runner, source)\nif err != nil {\n    var wrapped error\n    if errors.As(err, &wrapped) && strings.Contains(err.Error(), \"invalid v0.2 index\") {\n        log.Printf(\"schema mismatch for %s, cause: %v\", source, errors.Unwrap(err))\n    }\n}","preventionTips":["Pin index URLs to the schema version your CLI understands","Check the unwrapped cause for the exact failing JSON field","Beware proxies/captive portals injecting HTML into responses","Update the CLI when the upstream index schema changes"],"tags":["go","json","schema","skills-index"],"backgroundTag":"schema-validation-failed","analyzedSha":"7fd6ef3c07182257ce776cdc5a614e122d5bd4b3","analyzedAt":"2026-09-04T21:17:44.649Z","contentChangedAt":"2026-09-04T21:17:44.649Z","schemaVersion":2},"datasetVersion":"2026-09-12T02:17:10.037Z"}