What causes "add_attachment requires path" in larksuite/cli?

Add a non-empty `path` field to the add_attachment operation pointing at the file to attach

add_attachment requires path

Error message

add_attachment requires path

What it means

The mail draft shortcut validates each draft operation before applying it. An `add_attachment` operation without a non-empty `path` field cannot reference any file to upload, so the validator rejects the operation with this error. It is a client-side input validation failure; no API call is made.

Source

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

			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")
		}
	case "add_inline":
		if strings.TrimSpace(op.Path) == "" {
			return fmt.Errorf("add_inline requires path")
		}
		if strings.TrimSpace(op.CID) == "" {
			return fmt.Errorf("add_inline requires cid")
		}
	case "replace_inline":
		if !op.Target.hasKey() {
			return fmt.Errorf("replace_inline requires target with at least one of part_id or cid")
		}
		if strings.TrimSpace(op.Path) == "" {
			return fmt.Errorf("replace_inline requires path")

View on GitHub (pinned to 7fd6ef3c07)

Solutions

Add a non-empty `path` field to the add_attachment operation pointing at the file to attach
Check the source of the path value (env var, glob, config) for an empty or whitespace-only result before building the op
If you only meant to reference an existing attachment, use remove_attachment with a target (part_id/cid/token) instead

Example fix

// before
{"op":"add_attachment"}
// after
{"op":"add_attachment","path":"/tmp/report.pdf"}

Defensive patterns

Strategy: validation

Validate before calling

if strings.TrimSpace(op.Path) == "" {
    return fmt.Errorf("add_attachment requires path")
}

Type guard

func hasAddAttachmentPath(op DraftOp) bool { return strings.TrimSpace(op.Path) != "" }

Prevention

Always populate path when constructing add_attachment ops
Validate op lists with the same TrimSpace check before submitting
Distinguish add_attachment (path) from remove_attachment (target) requirements

When it happens

Trigger: Building a draft patch with `{"op":"add_attachment"}` but omitting `path`, setting it to an empty string, or passing only whitespace (e.g. `"path": " "`) — TrimSpace is applied so blank values fail.

Common situations: Programmatically generated op lists where the file variable was empty/unset; JSON patches copied from examples of remove_attachment (which uses target instead of path); a script looping over files where one entry lost its path field.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

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