larksuite/cli · error

Args field %s (--%s): json tag is not allowed on a CLI field

Error message

Args field %s (--%s): json tag is not allowed on a CLI field

What it means

When compiling a typed shortcut's Args struct, lark-cli rejects any field that carries a `json` struct tag. CLI input fields map to flags (declared via `flag`/`arg` plus `schema`, `cli`, `doc` tags), not to JSON serialization; a `json` tag usually signals the struct was copied from an API request/response type or is reused for wire encoding, which is forbidden so flag compilation stays deterministic.

Source

Thrown at shortcuts/common/typed_compile_args.go:134

				if inlineType.Kind() != reflect.Struct {
					return fmt.Errorf("Args field %s: arg:\"inline\" must be a struct, got %s", field.Name, field.Type)
				}
				if hasAnyTag(field, "flag", "schema", "cli", "doc", "json") {
					return fmt.Errorf("Args field %s: arg:\"inline\" cannot declare public input tags", field.Name)
				}
				if err := collectArgFields(inlineType, index, true, out, seenGo, supplements); err != nil {
					return err
				}
			default:
				return fmt.Errorf("Args field %s: unknown arg mode %q", field.Name, argMode)
			}
			continue
		}
		if !flagNamePattern.MatchString(flagName) {
			return fmt.Errorf("Args field %s: flag %q is not a canonical flag name", field.Name, flagName)
		}
		if hasAnyTag(field, "json") {
			return fmt.Errorf("Args field %s (--%s): json tag is not allowed on a CLI field", field.Name, flagName)
		}
		valueType, valueIndex, isProvided, err := unwrapProvided(field.Type)
		if err != nil {
			return fmt.Errorf("Args field %s (--%s): %w", field.Name, flagName, err)
		}
		schema, err := parseSchemaTag(field.Tag.Get("schema"), valueType, true)
		if err != nil {
			return fmt.Errorf("Args field %s (--%s): %w", field.Name, flagName, err)
		}
		cli, err := parseCLITag(field.Tag.Get("cli"))
		if err != nil {
			return fmt.Errorf("Args field %s (--%s): %w", field.Name, flagName, err)
		}
		var shape typedValueShape
		supplement, hasSupplement := supplements[flagName]
		if hasSupplement && supplement.Shape != nil {
			if schema.nullable != nil || schemaHasShapeConstraints(schema) {
				return fmt.Errorf("Args field %s (--%s): InputField.Shape conflicts with schema constraints or nullable declaration", field.Name, flagName)

View on GitHub (pinned to 7fd6ef3c07)

Solutions

1. Delete the `json:"..."` tag from the flagged Args field; CLI fields are never JSON-serialized.
2. If the struct must keep its json tags for API use, define a separate Args struct for the shortcut and convert between them.
3. Keep only the supported tags: flag/arg, schema, cli, doc.

Example fix

// before
type Args struct {
	Query string `flag:"query" schema:"required" json:"query"`
}
// after
type Args struct {
	Query string `flag:"query" schema:"required" doc:"Search query"`
}

for i := 0; i < reflect.TypeOf(Args{}).NumField(); i++ {
	if _, ok := reflect.TypeOf(Args{}).Field(i).Tag.Lookup("json"); ok {
		return fmt.Errorf("field %d has a forbidden json tag", i)
	}
}

func hasNoJSONTag(t reflect.Type) bool {
	for i := 0; i < t.NumField(); i++ {
		if _, ok := t.Field(i).Tag.Lookup("json"); ok { return false }
	}
	return true
}

When it happens

Trigger: Registering a shortcut whose Args struct has a field like `Query string \`flag:"query" schema:"required" json:"query"\``. The error fires in collectArgFields during command-set startup, right after the flag name passes the canonical-name check.

Common situations: Copying a struct from an internal/service payload type into Args and leaving the json tags on; sharing one struct between JSON output and CLI input; IDE auto-completing json tags on new fields.

Related errors

• cli token %q is duplicated
• unknown cli token %q
• invalid cli token %q
• Invalid column: {column!r}
• Invalid column index: {index}

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