larksuite/cli · error

set_header requires name

Error message

set_header requires name

What it means

Thrown by PatchOp.Validate() in shortcuts/mail/draft/model.go:302 when a set_header op has an empty or whitespace-only Name. The header name identifies which custom header to set on the mail, so it is mandatory. Value may be empty; name may not.

Source

Thrown at shortcuts/mail/draft/model.go:302

		if strings.TrimSpace(op.Address) == "" {
			return fmt.Errorf("%s requires address", op.Op)
		}
	case "set_reply_to":
		if len(op.Addresses) == 0 {
			return fmt.Errorf("set_reply_to requires addresses")
		}
	case "clear_reply_to":
	case "set_body", "set_reply_body":
	case "replace_body", "append_body":
		if !isBodyKind(op.BodyKind) {
			return fmt.Errorf("body_kind must be text/plain or text/html")
		}
		if op.Selector != "" && op.Selector != "primary" {
			return fmt.Errorf("selector must be primary")
		}
	case "set_header":
		if strings.TrimSpace(op.Name) == "" {
			return fmt.Errorf("set_header requires name")
		}
		if strings.ContainsAny(op.Name, ":\r\n") {
			return fmt.Errorf("set_header: header name must not contain ':', CR, or LF")
		}
		if strings.ContainsAny(op.Value, "\r\n") {
			return fmt.Errorf("set_header: header value must not contain CR or LF")
		}
	case "remove_header":
		if strings.TrimSpace(op.Name) == "" {
			return fmt.Errorf("remove_header requires name")
		}
	case "add_attachment":
		if strings.TrimSpace(op.Path) == "" {
			return fmt.Errorf("add_attachment requires path")
		}
	case "remove_attachment":
		if !op.Target.hasAnyKey() {
			return fmt.Errorf("remove_attachment requires target with at least one of part_id, cid, or token")

View on GitHub (pinned to 7fd6ef3c07)

Solutions

1. Provide the header name in op.Name, e.g. {"op":"set_header","name":"X-Custom-Id","value":"123"}.
2. Skip pairs with empty keys when building ops from a map.
3. Trim and check the key before emitting the op.

Example fix

// before
for k, v := range headers {
    ops = append(ops, PatchOp{Op: "set_header", Value: v}) // name forgotten
}

// after
for k, v := range headers {
    if strings.TrimSpace(k) == "" { continue }
    ops = append(ops, PatchOp{Op: "set_header", Name: k, Value: v})
}

if strings.TrimSpace(op.Name) == "" {
    return fmt.Errorf("set_header needs a name")
}

When it happens

Trigger: {"op":"set_header","value":"x"} with no name key; name:"" or name:" "; a variable feeding Name that was never assigned; JSON with omitempty dropping an empty name.

Common situations: Dynamic header construction from key/value maps where the key is missing; iterating over pairs and emitting an op for a blank key; template placeholders left unsubstituted.

Understand the failure class

Background: "must not be empty", "cannot be empty" — required-field validation errors across open-source libraries — this error's family across 41 libraries.

Related errors

• set_header: header name must not contain ':', CR, or LF
• set_header: header value must not contain CR or LF
• remove_header requires name
• set_recipients requires non-empty addresses
• %s requires address

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