What causes "variant %d: %w" in larksuite/cli?

Use the variant index in the error to find the bad Variants[i] entry.

variant %d: %w

Error message

variant %d: %w

What it means

When lowering a OneOfShape, each variant is itself lowered recursively; this wrapper prefixes any nested failure with the variant index (variant %d) so nested diagnostics like 'field "a": unsupported public shape X' can be traced to the exact variant. It identifies which arm of a one-of declaration is malformed.

Source

Thrown at shortcuts/common/typed_shape.go:129

			}
			fields[index] = typedValueField{
				Name: field.Name, Description: field.Description, Required: field.Required, Shape: fieldShape,
			}
		}
		additional, err := lowerAuthoringShape(value.AdditionalPropertiesShape)
		if err != nil {
			return nil, err
		}
		return typedObjectShape{
			Fields: fields, AdditionalProperties: value.AdditionalProperties,
			AdditionalPropertiesShape: additional,
		}, nil
	case command.OneOfShape:
		variants := make([]typedValueShape, len(value.Variants))
		for index, variant := range value.Variants {
			lowered, err := lowerAuthoringShape(variant)
			if err != nil {
				return nil, fmt.Errorf("variant %d: %w", index, err)
			}
			variants[index] = lowered
		}
		return typedOneOfShape{Variants: variants}, nil
	default:
		return nil, fmt.Errorf("unsupported public shape %T", shape)
	}
}

View on GitHub (pinned to 7fd6ef3c07)

Solutions

Use the variant index in the error to find the bad Variants[i] entry.
Lower into the chain: the wrapped error names the nested field/type that is actually unsupported; fix that concrete shape.
Ensure every variant uses documented command.*Shape types only.

Example fix

// before
command.OneOfShape{Variants: []command.ValueShape{command.StringShape{}, rawMapShape{}}}
// after
command.OneOfShape{Variants: []command.ValueShape{command.StringShape{}, command.ObjectShape{Fields: ...}}}

Defensive patterns

Strategy: validation

Validate before calling

for i, v := range oneOf.Variants {
    if !isSupportedShape(v) {
        return fmt.Errorf("variant %d: unsupported shape %T", i, v)
    }
}

Prevention

Run compileData on input definitions in tests to surface variant errors at build time.
Keep one-of variants uniform: build each variant with the same helper so a bad type cannot slip into one arm.
After renaming/replacing shape types, grep for the old type across all Variants slices.

When it happens

Trigger: A OneOfShape whose Variants slice contains an entry (or a nested object inside it) holding an unsupported/custom shape type or a typed-nil shape, causing the recursive lowerAuthoringShape call to fail.

Common situations: Building polymorphic inputs (e.g. user vs. open_id vs. union_id resolvers) where one variant was authored with the wrong shape type; refactors that renamed or replaced a shape type but missed one variant.

Related errors

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