What causes "%s field %s (%s): description is required via doc" in larksuite/cli?

Add a meaningful `doc:"..."` tag describing the field's purpose and expectations

%s field %s (%s): description is required via doc

Error message

%s field %s (%s): description is required via doc

What it means

Every field of an Input struct (input=true) must provide a human-readable description via a non-empty `doc:` tag. The compiler uses it to generate schema/help text for agents and users; an undocumented input field is rejected at compile time.

Source

Thrown at shortcuts/common/typed_compile_data.go:245

		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)
		if err != nil {
			return typedObjectShape{}, fmt.Errorf("%s field %s (%s): %w", path, field.Name, name, err)
		}
		shape.Fields = append(shape.Fields, typedValueField{Name: name, Description: description, Required: schema.required, Shape: fieldShape})
	}
	return shape, nil
}

func validateShape(shape typedValueShape, path string) error {
	if shape == nil {
		return fmt.Errorf("%s is nil", path)
	}
	switch value := shape.(type) {
	case anyJSONShape:
	case typedStringShape:
		if value.MinLength != nil && *value.MinLength < 0 || value.MaxLength != nil && *value.MaxLength < 0 {

View on GitHub (pinned to 7fd6ef3c07)

Solutions

Add a meaningful `doc:"..."` tag describing the field's purpose and expectations
Fill in an existing empty doc tag with real content (not spaces)
If the field is output-only, confirm you intended input=true compilation

Example fix

// before
Limit int `json:"limit" schema:"optional"`
// after
Limit int `json:"limit" schema:"optional" doc:"Maximum number of items to return (1-100)"`

Defensive patterns

Strategy: validation

Validate before calling

if isInput && strings.TrimSpace(f.Tag.Get("doc")) == "" {
    return fmt.Errorf("field %s: doc tag required for input fields", f.Name)
}

Prevention

Write the doc: tag whenever you add an input field — treat it as part of the field
Never leave doc:"" placeholders; describe units, ranges, and expectations
Keep Data-struct docs optional but Input-struct docs mandatory in review checklists

When it happens

Trigger: Compiling an Input struct where a field's `doc:` tag is missing, empty, or whitespace-only (`strings.TrimSpace` yields ""), via compileStructShape.

Common situations: Adding a new input field and skipping documentation; leaving `doc:""` as a TODO; tags placed on the wrong line/field after refactor; using only a json tag copied from a Data struct (docs required only for inputs).

Related errors

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