What causes "byte slice or array %s requires an explicit Shape" in larksuite/cli?

Change the field type to string if the API expects plain text/IDs.

byte slice or array %s requires an explicit Shape

Error message

byte slice or array %s requires an explicit Shape

What it means

The shape compiler cannot decide how []byte should appear in JSON: encoding/json base64-encodes byte slices, which rarely matches what a Lark API field actually expects. Rather than silently emit a base64 string schema, shapeForType rejects byte slices/arrays and asks for an explicit Shape or a declared string field.

Source

Thrown at shortcuts/common/typed_compile_data.go:141

	case reflect.Float32, reflect.Float64:
		numberShape := typedNumberShape{Minimum: schema.minimum, Maximum: schema.maximum}
		for _, raw := range schema.enum {
			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)

View on GitHub (pinned to 7fd6ef3c07)

Solutions

Change the field type to string if the API expects plain text/IDs.
If base64 is correct, declare the field as string and encode bytes yourself before producing Data.
Supply an explicit Output.Data.Shape describing the field as a string (or array of integers) shape.
Wrap bytes in a struct implementing encoding.TextMarshaler only if you also give an explicit Shape — custom-encoding types are likewise rejected.

Example fix

// before
type Data struct {
    Content []byte `json:"content"`
}

// after
type Data struct {
    Content string `json:"content"` // base64-encode before filling
}

Defensive patterns

Strategy: validation

Validate before calling

func hasByteSlice(t reflect.Type) bool {
    for t.Kind() == reflect.Pointer { t = t.Elem() }
    switch t.Kind() {
    case reflect.Slice, reflect.Array:
        if t.Elem().Kind() == reflect.Uint8 { return true }
        return hasByteSlice(t.Elem())
    case reflect.Struct:
        for i := 0; i < t.NumField(); i++ {
            if hasByteSlice(t.Field(i).Type) { return true }
        }
    }
    return false
}

Type guard

func isByteSlice(t reflect.Type) bool {
    return (t.Kind() == reflect.Slice || t.Kind() == reflect.Array) && t.Elem().Kind() == reflect.Uint8
}

Prevention

Model binary API fields as string and encode (base64/hex) explicitly before filling Data.
Do not rely on encoding/json's implicit base64 of []byte in wire structs.
Add a unit test that constructs the shortcut command set so registration-time compile errors fail the build.

When it happens

Trigger: A Data struct field typed []byte, [N]byte, [][]byte, or any slice/array whose element kind is Uint8 reaches shapeForType via collectArgFields or compileStructShape during registration.

Common situations: Fields meant to hold file content, tokens, or binary IDs modeled as []byte; porting code where encoding/json's base64 behavior was relied on; dataclasses generated from OpenAPI binary formats.

Related errors

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