What causes "%s field %s json tag must explicitly name the field" in larksuite/cli?

Write the wire name explicitly before the comma, e.g. `json:"user_id,omitempty"`

%s field %s json tag must explicitly name the field

Error message

%s field %s json tag must explicitly name the field

What it means

The compiler found a `json` tag whose name portion is empty, e.g. `json:",omitempty"`. The library requires each field to explicitly name itself in the tag so wire names are stable and searchable; Go's default fallback to the field name is not accepted. This keeps compiled schemas deterministic and independent of Go identifier casing rules.

Source

Thrown at shortcuts/common/typed_compile_data.go:211

	shape := typedObjectShape{}
	seen := make(map[string]string)
	for i := 0; i < t.NumField(); i++ {
		field := t.Field(i)
		if !field.IsExported() {
			continue
		}
		rawJSON, ok := field.Tag.Lookup("json")
		if !ok {
			return typedObjectShape{}, fmt.Errorf("%s field %s must declare json tag", path, field.Name)
		}
		parts := strings.Split(rawJSON, ",")
		name := parts[0]
		if name == "-" {
			continue
		}
		if name == "" {
			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)

View on GitHub (pinned to 7fd6ef3c07)

Solutions

Write the wire name explicitly before the comma, e.g. `json:"user_id,omitempty"`
Use `json:"-"` if the field must be excluded from the compiled shape

Example fix

// before
Optional string `json:",omitempty"`
// after
Optional string `json:"optional,omitempty"`

Defensive patterns

Strategy: validation

Validate before calling

for i := 0; i < t.NumField(); i++ {
    f := t.Field(i)
    tag, ok := f.Tag.Lookup("json")
    if ok && strings.Split(tag, ",")[0] == "" {
        return fmt.Errorf("field %s must name itself in the json tag", f.Name)
    }
}

Prevention

Never write json tags starting with a comma
Always copy the full tag `json:"name,opts"` including the name
Review diffs for mechanical tag edits that drop names

When it happens

Trigger: A struct field tagged like `json:",omitempty"` or `json:",string"` processed by compileStructShape (via compileData or shapeForType).

Common situations: Retrofitting omitempty onto an existing field by prepending a comma and forgetting the name; mechanically adding `json:"..."` tags via tooling that leaves the name blank; intent to rely on Go's default naming, which this compiler forbids.

Related errors

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