siyuan-note/siyuan · error

--block is required for non-detached rows

Error message

--block is required for non-detached rows

What it means

The `siyuan database item add` command supports two row modes: bound to an existing block (`--block`) or detached (`--detached`). When the row is NOT detached, blockID is mandatory because the kernel creates a bound attribute-view entry anchored to that block; RunE returns this error when `--detached` is absent and `--block` is empty.

Solutions

1. If the row should be bound to a block, pass its ID: `--block <blockID>`
2. If the row should be standalone, add the `--detached` flag
3. If `--block` comes from a variable, verify the variable is non-empty (e.g. `: "${BLOCK_ID:?}"` in bash) before invoking

Example fix

// before
siyuan database item add --av $AV_ID --content "todo"
// after
siyuan database item add --av $AV_ID --content "todo" --detached
// or
siyuan database item add --av $AV_ID --block $BLOCK_ID --content "todo"

if [ -z "$BLOCK_ID" ] && [ "$DETACHED" != "true" ]; then
  echo "provide --block or --detached" >&2; exit 1
fi

When it happens

Trigger: Running `siyuan database item add --av <avID>` without either `--block <blockID>` or the `--detached` boolean flag. Also triggered by `--detached=false` with no `--block`.

Common situations: Adding a detached-style row but forgetting the `--detached` switch; intending to bind a block but forgetting to copy its block ID; scripts that conditionally pass --block but always omit --detached.

Understand the failure class

Background: "--flag is required" and "must specify" CLI errors: how missing-required-flag validation works and how to fix it — this error's family across 20 libraries.

Related errors

• --av and --ids are required
• --av, --key, --item and --value are required
• --av and --key are required
• --av is required
• --av, --name and --type are required

AI-assisted analysis of siyuan-note/siyuan@9f775e8a12 (2026-09-19). Data as JSON: /api/errors/6208cc9d50598da0. Report an issue: GitHub.

Appendix: source

Thrown at kernel/cli/cmd/database.go:258

}

var databaseItemAddCmd = &cobra.Command{
	Use:   "add --av <avID>",
	Short: "Add a row to database",
	RunE: func(cmd *cobra.Command, args []string) error {
		avID, _ := cmd.Flags().GetString("av")
		content, _ := cmd.Flags().GetString("content")
		blockID, _ := cmd.Flags().GetString("block")
		viewID, _ := cmd.Flags().GetString("view")
		groupID, _ := cmd.Flags().GetString("group")
		previousID, _ := cmd.Flags().GetString("previous")
		isDetached, _ := cmd.Flags().GetBool("detached")
		ignoreFill, _ := cmd.Flags().GetBool("ignore-default-fill")
		if avID == "" {
			return fmt.Errorf("--av is required")
		}
		if !isDetached && blockID == "" {
			return fmt.Errorf("--block is required for non-detached rows")
		}

		if dryRun {
			fmt.Printf("[dry-run] Would add row to database %s\n", avID)
			return nil
		}

		src := map[string]any{
			"isDetached": isDetached,
		}
		if blockID != "" {
			src["id"] = blockID
		}
		if content != "" {
			src["content"] = content
		}
		srcs := []map[string]any{src}

View on GitHub (pinned to 9f775e8a12)