larksuite/cli · error

array item: %w

Error message

array item: %w

What it means

This is a wrapping error: while deriving the schema of an array field, shapeForType recursed into the element type and that recursion failed (e.g. the element is json.RawMessage, []byte, a map, an interface, or has its own incompatible constraints). The compiler prefixes the element error with "array item:" to point at the offending position in the type tree.

Source

Thrown at shortcuts/common/typed_compile_data.go:149

		}
		if hasStringConstraints(schema) || hasItemConstraints(schema) || schema.format != "" {
			return nil, fmt.Errorf("number field has incompatible schema constraint")
		}
		shape = numberShape
	case reflect.Slice, reflect.Array:
		if baseType == jsonRawMessageType {
			return nil, fmt.Errorf("json.RawMessage requires an explicit Shape")
		}
		if baseType.Elem().Kind() == reflect.Uint8 {
			return nil, fmt.Errorf("byte slice or array %s requires an explicit Shape", baseType)
		}
		if len(schema.enum) > 0 || hasStringConstraints(schema) || hasNumberConstraints(schema) || schema.format != "" {
			return nil, fmt.Errorf("array field has incompatible schema constraint")
		}
		elementSchema := schemaTag{required: true}
		elementShape, err := shapeForType(baseType.Elem(), elementSchema, input, active)
		if err != nil {
			return nil, fmt.Errorf("array item: %w", err)
		}
		shape = typedArrayShape{Items: elementShape, MinItems: schema.minItems, MaxItems: schema.maxItems}
	case reflect.Struct:
		if implementsCustomEncoding(baseType) {
			return nil, fmt.Errorf("custom JSON type %s requires an explicit Shape", baseType)
		}
		if len(schema.enum) > 0 || hasStringConstraints(schema) || hasNumberConstraints(schema) || hasItemConstraints(schema) || schema.format != "" {
			return nil, fmt.Errorf("object field has incompatible schema constraint")
		}
		object, err := compileStructShape(baseType, input, baseType.String(), active)
		if err != nil {
			return nil, err
		}
		shape = object
	case reflect.Map:
		return nil, fmt.Errorf("map type %s requires an explicit Shape", baseType)
	case reflect.Interface:
		return nil, fmt.Errorf("interface type %s requires an explicit Shape", baseType)

View on GitHub (pinned to 7fd6ef3c07)

Solutions

  1. Read the wrapped cause below this message to find which element type failed and why.
  2. Replace the offending element type with a concrete mappable type (string, int, bool, float, plain struct).
  3. Give an explicit Output.Data.Shape describing the array's item shape.
  4. If items are truly arbitrary, restructure Data as `any` or provide a Shape with permissive items.

Example fix

// before
Rows []map[string]any `json:"rows"`

// after
type Row struct {
    Name string `json:"name"`
    Val  int    `json:"val"`
}
Rows []Row `json:"rows"`
Defensive patterns

Strategy: try-catch

Validate before calling

// Pre-walk element types before registration:
func checkArrayElems(t reflect.Type) error {
    for t.Kind() == reflect.Pointer { t = t.Elem() }
    if t.Kind() == reflect.Slice || t.Kind() == reflect.Array {
        if err := checkArrayElems(t.Elem()); err != nil {
            return fmt.Errorf("array item: %w", err)
        }
    }
    return nil
}

Try / catch

if _, err := compileShortcut(cmd); err != nil {
    var chain []string
    for e := err; e != nil; e = errors.Unwrap(e) {
        chain = append(chain, e.Error())
    }
    // innermost entry names the failing element type
    slog.Error("data shape compile failed", "chain", chain)
    return err
}

Prevention

When it happens

Trigger: Declaring fields like []map[string]string, []json.RawMessage, or [][]byte; also []someStruct where someStruct itself fails compilation — the inner cause is chained via %w.

Common situations: Loosely typed collections from generic API clients; nested DTOs that were valid under encoding/json but have no static shape; recently refactored element types.

Related errors

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