larksuite/cli · error

array field has incompatible schema constraint

Error message

array field has incompatible schema constraint

What it means

An array-typed field was tagged with schema constraints that only make sense for other kinds: enum values, string constraints (minLength/pattern-style), number constraints (minimum/maximum), or a format. An array shape supports only item constraints (minItems/maxItems), so the compiler rejects the combination as unsatisfiable.

Source

Thrown at shortcuts/common/typed_compile_data.go:144

			v, err := parseFiniteFloatBits(raw, baseType.Bits())
			if err != nil {
				return nil, fmt.Errorf("enum value %q is not a finite number", raw)
			}
			numberShape.Enum = append(numberShape.Enum, v)
		}
		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
		}

View on GitHub (pinned to 7fd6ef3c07)

Solutions

1. Move the constraint to the element type by using an item-appropriate tag or modeling items as a named struct/string with the constraint.
2. Keep only minItems/maxItems (item constraints) on the array field and drop enum/format/string/number tags.
3. If a value set is intended, declare the field as a single string with enum, or give an explicit Output.Data.Shape with a constrained-items array.

Example fix

// before
IDs []string `json:"ids" schema:"enum=user_1,user_2"`

// after
IDs []string `json:"ids" schema:"minItems=1"` // enum belongs on a scalar field or explicit Shape

func arrayTagsValid(f reflect.StructField) bool {
    if f.Type.Kind() != reflect.Slice && f.Type.Kind() != reflect.Array { return true }
    tag := f.Tag.Get("schema")
    for _, bad := range []string{"enum=", "format=", "minLength=", "maxLength=", "minimum=", "maximum="} {
        if strings.Contains(tag, bad) { return false }
    }
    return true // only minItems=/maxItems= allowed on arrays
}

When it happens

Trigger: A struct field like `[]string `+"`"+`schema:"enum=a,b"`+"`"+` or `+"`"+`schema:"format=date"`+"`"+` with a slice/array type is processed by shapeForType's reflect.Slice/Array case during command registration.

Common situations: Copy-pasting a schema tag from a string field onto a slice field; adding `format:uri` intending it to apply to items; schema-tag-generating tools mislabeling array fields.

Related errors

• object field has incompatible schema constraint
• Invalid column: {column!r}
• Invalid column index: {index}
• anchor outside sheet: {position!r}
• Missing row_count/column_count for sheet {sheet_title(sheet)

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