What causes "%s field %s (%s): %w" in larksuite/cli?

Read the wrapped cause message (%w) for the actual parse failure and fix the `schema:` tag accordingly

%s field %s (%s): %w

Error message

%s field %s (%s): %w

What it means

This is a wrapping error: parsing the field's `schema:` tag failed and the cause (e.g. invalid schema option, wrong type usage) is preserved via %w. It adds context — which struct path, field, and JSON name — around the underlying parseSchemaTag error.

Source

Thrown at shortcuts/common/typed_compile_data.go:229

			return typedObjectShape{}, fmt.Errorf("%s field %s json tag must explicitly name the field", path, field.Name)
		}
		omitempty := false
		for _, option := range parts[1:] {
			switch option {
			case "omitempty":
				omitempty = true
			case "":
			default:
				return typedObjectShape{}, fmt.Errorf("%s field %s has unsupported json option %q", path, field.Name, option)
			}
		}
		if previous, exists := seen[name]; exists {
			return typedObjectShape{}, fmt.Errorf("%s field %s JSON name %q duplicates field %s", path, field.Name, name, previous)
		}
		seen[name] = field.Name
		schema, err := parseSchemaTag(field.Tag.Get("schema"), field.Type, input)
		if err != nil {
			return typedObjectShape{}, fmt.Errorf("%s field %s (%s): %w", path, field.Name, name, err)
		}
		if !input && schema.defaultValue.Set {
			return typedObjectShape{}, fmt.Errorf("%s field %s (%s): Data field cannot declare default", path, field.Name, name)
		}
		if schema.required && omitempty {
			return typedObjectShape{}, fmt.Errorf("%s field %s (%s): required Data field cannot use omitempty", path, field.Name, name)
		}
		if schema.optional && !omitempty {
			return typedObjectShape{}, fmt.Errorf("%s field %s (%s): optional Data field must use omitempty", path, field.Name, name)
		}
		if isNilCapable(field.Type) && schema.nullable == nil {
			return typedObjectShape{}, fmt.Errorf("%s field %s (%s): nil-capable field must declare nullable or nonnullable", path, field.Name, name)
		}
		description := strings.TrimSpace(field.Tag.Get("doc"))
		if input && description == "" {
			return typedObjectShape{}, fmt.Errorf("%s field %s (%s): description is required via doc", path, field.Name, name)
		}
		fieldShape, err := shapeForType(field.Type, schema, input, active)

View on GitHub (pinned to 7fd6ef3c07)

Solutions

Read the wrapped cause message (%w) for the actual parse failure and fix the `schema:` tag accordingly
Check valid schema keywords in the library's schema tag documentation
Remove options that don't apply to the field's type

Example fix

// before
Name string `json:"name" schema:"requird" doc:"..."`
// after
Name string `json:"name" schema:"required" doc:"..."`

Defensive patterns

Strategy: try-catch

Validate before calling

// Validate schema tags before registration using the library's own parser
if err := parseSchemaTag(f.Tag.Get("schema"), f.Type, input); err != nil {
    return fmt.Errorf("field %s: %w", f.Name, err)
}

Try / catch

shape, err := common.ShapeForType(myType)
if errors.Is(err, someSchemaParseErr) {
    // inspect errors.Unwrap / %s for the offending schema option
    log.Fatalf("invalid schema tag: %v", err)
}

Prevention

Copy schema keywords only from documented examples
Keep schema options minimal per field
Add compile tests covering each distinct schema option you use

When it happens

Trigger: Any malformed or invalid `schema:` tag (e.g. `schema:"requird"`, conflicting options, type-incompatible option) on a field compiled through compileStructShape.

Common situations: Typos in schema keywords; combining mutually exclusive options like required+optional; applying an option invalid for the field's Go type; SDK version change renaming a schema keyword.

Related errors

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