siyuan-note/siyuan · error

--attr is required (format: name=value)

Error message

--attr is required (format: name=value)

What it means

Thrown by the `attr set` cobra subcommand when the `--attr` flag (a StringArray) is absent or empty. The command requires at least one `name=value` pair to know which block attribute to write. It is a pure argument-guard: the model layer is never reached.

Source

Thrown at kernel/cli/cmd/attr.go:82

Common attributes:
  icon       Emoji hex codepoint (e.g. "1f4ca"), emoji character (e.g. "📊"), custom image path (e.g. "1/b3log.png"), network image URL (e.g.
             "https://example.com/icon.png"), or dynamic icon URL (e.g. "api/icon/getDynamicIcon?type=8&color=%23d23f31&content=SiYuan&id=xxx").
  title-img  CSS background-image format (e.g. 'background-image:url("assets/example.jpg")').
             DO NOT use a bare asset path.
  tags       Comma-separated tag names.

Examples:
  siyuan-kernel attr set --id 20260605100657-v080a4j --attr icon=1f4ca
  siyuan-kernel attr set --id 20260605100657-v080a4j --attr title-img='background-image:url("assets/example.jpg")'`,
	RunE: func(cmd *cobra.Command, args []string) error {
		id, _ := cmd.Flags().GetString("id")
		if id == "" {
			return fmt.Errorf("--id is required")
		}

		attrFlags, _ := cmd.Flags().GetStringArray("attr")
		if len(attrFlags) == 0 {
			return fmt.Errorf("--attr is required (format: name=value)")
		}

		nameValues := make(map[string]string, len(attrFlags))
		for _, a := range attrFlags {
			parts := strings.SplitN(a, "=", 2)
			if len(parts) != 2 {
				return fmt.Errorf("invalid attr format [%s], expected name=value", a)
			}
			nameValues[strings.TrimSpace(parts[0])] = parts[1]
		}

		if dryRun {
			var parts []string
			for k, v := range nameValues {
				parts = append(parts, fmt.Sprintf("%s=%s", k, v))
			}
			fmt.Printf("[dry-run] Would set attributes on block %s: %s\n", id, strings.Join(parts, ", "))
			return nil

View on GitHub (pinned to 251596fc0d)

Solutions

1. Add at least one `--attr name=value`, e.g. `siyuan-kernel attr set --id 20260605100657-v080a4j --attr icon=1f4ca`
2. For multiple attributes repeat the flag: `--attr icon=1f4ca --attr title-img='background-image:url("x.jpg")'`
3. Run `siyuan-kernel attr set --help` to confirm the exact flag spelling and the `name=value` format

Example fix

// before
siyuan-kernel attr set --id 20260605100657-v080a4j
// after
siyuan-kernel attr set --id 20260605100657-v080a4j --attr icon=1f4ca

// Before invoking the CLI in a script, assert the attr payload is non-empty.
attrs := []string{"icon=1f4ca"} // built by your script
if len(attrs) == 0 {
    return fmt.Errorf("refusing to run: no --attr values provided")
}

When it happens

Trigger: Running `siyuan-kernel attr set --id <blockID>` without any `--attr` flag, or passing `--attr` with zero values. The check is `len(attrFlags) == 0` on the resolved StringArray.

Common situations: Forgetting the `--attr` argument when scripting attribute updates; copy-pasting the example from `--help` but dropping the attribute portion; expecting attributes to be read from stdin.

Related errors

• --ids is required
• invalid attr format [%s], expected name=value
• --id is required
• --parent is required
• --id and --parent are required

AI-assisted analysis of siyuan-note/siyuan@251596fc0d (2026-08-12). Data as JSON: /api/errors/c9bf524a96c76f05. Report an issue: GitHub.