larksuite/cli · error

invalid RequiredCLIVersion %q: %w

Error message

invalid RequiredCLIVersion %q: %w

What it means

satisfiesRequiredCLIVersion parses a plugin's RequiredCLIVersion constraint; if the version suffix after the operator fails parseSemverPrefix, it reports "invalid RequiredCLIVersion %q: %w" with the parse error. It protects installOne from installing a plugin whose version constraint is malformed.

Source

Thrown at internal/platform/version.go:61

// Returns false and an error when constraint is malformed -- callers
// should treat parse errors as fail-closed so an authoring mistake in
// the plugin does not silently load against the wrong CLI version.
//
// **Order of checks**: constraint syntax is validated FIRST, before the
// DEV-build short-circuit. A malformed constraint is a plugin authoring
// bug; we surface it even on DEV builds so the typo can be caught
// during plugin development instead of waiting for the first tagged
// release to expose it.
func satisfiesRequiredCLIVersion(buildVersion, constraint string) (bool, error) {
	constraint = strings.TrimSpace(constraint)
	if constraint == "" {
		return true, nil
	}

	op, rhs := splitConstraint(constraint)
	rv, err := parseSemverPrefix(rhs)
	if err != nil {
		return false, fmt.Errorf("invalid RequiredCLIVersion %q: %w", constraint, err)
	}

	if buildVersion == "" || buildVersion == "DEV" {
		return true, nil
	}

	bv, err := parseSemverPrefix(buildVersion)
	if err != nil {
		// Build version is unparseable -- treat as DEV so an exotic
		// build tag doesn't lock plugins out.
		return true, nil //nolint:nilerr // intentional fail-open for unparseable buildVersion
	}
	cmp := compareSemver(bv, rv)
	switch op {
	case "=", "":
		return cmp == 0, nil
	case ">=":
		return cmp >= 0, nil

View on GitHub (pinned to 7fd6ef3c07)

Solutions

1. Fix the plugin manifest's RequiredCLIVersion to a supported form: optional operator ("", "=", ">=", ">", "<=", "<") plus a valid semver prefix like 1.2 or 1.2.3.
2. Check the wrapped parse error (%w) to see exactly what the parser rejected.
3. Use a released plugin version with a valid manifest.
4. If you author plugins, add manifest validation to your release pipeline.

Example fix

// before
"RequiredCLIVersion": "1.2.x || ^2"
// after
"RequiredCLIVersion": ">=1.2"

var rvRe = regexp.MustCompile(`^(>=|<=|>|<|=)?\d+(\.\d+)?(\.\d+)?$`)
func validConstraint(c string) bool { return rvRe.MatchString(c) }
// check before install: validConstraint(plugin.RequiredCLIVersion)

When it happens

Trigger: Installing a plugin whose manifest declares RequiredCLIVersion in a non-semver form after the operator — e.g. "1.2", "v1.2.x-beta.3+meta", "1.2.3.4", or an empty/garbled value.

Common situations: Hand-edited plugin manifests; a plugin author bumped versions with a tool emitting unsupported formats; copy-pasted constraints from another ecosystem (npm/cargo style ranges).

Related errors

• invalid RequiredCLIVersion %q: unknown operator %q
• plugin %q rule invalid: %w
• L1: _meta.envelope_version = %q, want "1.0"
• Invalid column: {column!r}
• Invalid column index: {index}

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