document block [ ] cannot be used as a previous sibling…

Error message

document block [%s] cannot be used as a previous sibling; use it as --parent instead

What it means

A document block ('d' type) was supplied as --previousID (previous sibling) in a block move. Documents cannot serve as siblings in the block tree; to place a block inside or after a document you must reference the document as the parent via --parent instead. Raised in validateBlockMove at kernel/cli/cmd/block.go:465.

Solutions

Pass the document ID as --parent instead of --previous so the block is placed within that document
If you need the block after a specific existing block, use the ID of that inner block (not the doc ID) as --previous
Query the document's child blocks first and pick the actual last block ID as the previous sibling

Example fix

// before
siyuan block move --id 20240101120000-block1 --previous 20240101120000-document
// after
siyuan block move --id 20240101120000-block1 --parent 20240101120000-document

Defensive patterns

Strategy: validation

Validate before calling

type=$(siyuan block batch-get --ids "$PREVIOUS_ID" | jq -r '.[0].type // empty')
if [ "$type" = "d" ]; then
  exec siyuan block move --id "$ID" --parent "$PREVIOUS_ID"
fi

Type guard

function isDocumentBlock(info) { return info && info.type === 'd'; }

Prevention

Check the type of any --previous target; documents must be used as --parent
When appending to a document, resolve its last child block and use that as --previous
Never feed doc-tree listings directly into move scripts without type filtering

When it happens

Trigger: Running a block move command with --previous <docID> where the ID resolves to a block tree node with Type "d". Typically happens when scripting moves that append content after a document.

Common situations: Trying to insert a block at the end of a document by passing the doc ID as previous sibling; confusing root/document IDs with the ID of the last child block; generating move scripts from doc-tree listings instead of block listings.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

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

Appendix: source

Thrown at kernel/cli/cmd/block.go:465

	},
}

func validateBlockMove(id, parentID, previousID string) error {
	bt := treenode.GetBlockTree(id)
	if nil == bt {
		return fmt.Errorf("block not found: %s", id)
	}
	if "d" == bt.Type {
		return fmt.Errorf("document block [%s] cannot be moved with block move; use document move instead", id)
	}

	if "" != previousID {
		previousBt := treenode.GetBlockTree(previousID)
		if nil == previousBt {
			return fmt.Errorf("previous block not found: %s", previousID)
		}
		if "d" == previousBt.Type {
			return fmt.Errorf("document block [%s] cannot be used as a previous sibling; use it as --parent instead", previousID)
		}
		return nil
	}
	if err := treenode.CheckListItemNesting(parentID, id); err != nil {
		return err
	}
	return treenode.CheckContainerParent(parentID)
}

var blockBatchGetCmd = &cobra.Command{
	Use:   "batch-get --ids id1,id2,...",
	Short: "Batch get block info",
	RunE: func(cmd *cobra.Command, args []string) error {
		idsStr, _ := cmd.Flags().GetString("ids")
		if idsStr == "" {
			return fmt.Errorf("--ids is required")
		}
		ids := splitIDs(idsStr)

View on GitHub (pinned to 9f775e8a12)