What causes "invalid v0.2 index: %w" in larksuite/cli?

Curl the source URL and inspect the body — confirm it is the expected v0.2 index JSON

invalid v0.2 index: %w

Error message

invalid v0.2 index: %w

What it means

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.

Source

Thrown at internal/skillscheck/sync.go:356

			Action: "failed",
			Layout: targetLayout,
			Err:    fmt.Errorf("suite skills sync failed: %s", strings.Join(reasons, "; ")),
			Detail: strings.Join(reasons, "\n"),
			Force:  opts.Force,
		}
	}

	return fallbackSeparate(opts, previous, readable, localOfficial, installed, fallbackPlan, reasons)
}

func fetchOfficialSkills(runner SkillsRunner, source string) ([]string, error) {
	result := runner.FetchSkillsIndex(source)
	if result == nil || result.Err != nil {
		return nil, fmt.Errorf("index request failed: %s", resultDetail(result))
	}
	official, err := ParseOfficialSkillsIndexJSON(result.Stdout.String())
	if err != nil {
		return nil, fmt.Errorf("invalid v0.2 index: %w", err)
	}
	if len(official) == 0 {
		return nil, fmt.Errorf("v0.2 index contains no skills")
	}
	return official, nil
}

func listInstalledSkills(runner SkillsRunner) ([]installedSkill, error) {
	jsonResult := runner.ListGlobalSkillsJSON()
	if jsonResult != nil && jsonResult.Err == nil {
		if installed, err := parseInstalledSkillsJSON(jsonResult.Stdout.String()); err == nil {
			return installed, nil
		}
	}

	textResult := runner.ListGlobalSkills()
	if textResult != nil && textResult.Err == nil {
		names := ParseSkillsList(textResult.Stdout.String())

View on GitHub (pinned to 7fd6ef3c07)

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

Example fix

// before: treating body blindly
official, err := ParseOfficialSkillsIndexJSON(result.Stdout.String())
// after: diagnose the body when parse fails
official, err := ParseOfficialSkillsIndexJSON(result.Stdout.String())
if err != nil {
    log.Printf("index body head: %.200s", result.Stdout.String())
    return nil, fmt.Errorf("invalid v0.2 index: %w", err)
}

Defensive patterns

Strategy: validation

Validate before calling

body := result.Stdout.String()
if !strings.HasPrefix(strings.TrimSpace(body), "{") {
    return errors.New("index endpoint did not return JSON (likely HTML error page)")
}
var probe map[string]any
if json.Unmarshal([]byte(body), &probe) != nil {
    return errors.New("index body is not valid JSON")
}

Type guard

func looksLikeV02Index(body string) bool {
    var idx struct {
        Skills []map[string]any `json:"skills"`
    }
    return json.Unmarshal([]byte(body), &idx) == nil && idx.Skills != nil
}

Try / catch

official, err := fetchOfficialSkills(runner, source)
if err != nil {
    var wrapped error
    if errors.As(err, &wrapped) && strings.Contains(err.Error(), "invalid v0.2 index") {
        log.Printf("schema mismatch for %s, cause: %v", source, errors.Unwrap(err))
    }
}

Prevention

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

When it happens

Trigger: SyncSkills -> fetchOfficialSkills where ParseOfficialSkillsIndexJSON(result.Stdout.String()) returns a non-nil error.

Common situations: 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.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

AI-assisted analysis of larksuite/cli@7fd6ef3c07 (2026-09-04). Data as JSON: /api/errors/66ae6c7accbba8bc. Report an issue: GitHub.