document block [%s] cannot be used as a previous sibling; us

Error message

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

What it means

Thrown inside `validateBlockMove` when `--previous` resolves to a block of type `"d"` (document). A document cannot act as a previous sibling of a block move — documents are not siblings of in-document blocks. The error directs the user to make that document the `--parent` instead, which is the structurally correct relationship.

Source

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

	},
}

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 251596fc0d)

Solutions

Move the document ID from `--previous` to `--parent`: `siyuan-kernel block move --id <mover> --parent <docID>`
If you truly need sibling positioning, use a non-document block ID for `--previous`
Check the candidate's type with `block get` to confirm it is not type `d`

Example fix

// before
siyuan-kernel block move --id <mover> --parent <dest> --previous <docID>
// after
siyuan-kernel block move --id <mover> --parent <docID>

Defensive patterns

Strategy: validation

Validate before calling

// A document cannot be a previous sibling; reject or redirect to --parent.
if previousID != "" {
    pbt := treenode.GetBlockTree(previousID)
    if pbt == nil {
        return fmt.Errorf("previous sibling %s not found", previousID)
    }
    if pbt.Type == "d" {
        // route the document ID to --parent instead
        return fmt.Errorf("previous %s is a document; pass it as --parent", previousID)
    }
}

Type guard

func isDocumentBlock(id string) bool {
    bt := treenode.GetBlockTree(id)
    return bt != nil && bt.Type == "d"
}

Prevention

Distinguish container/parent slots from sibling slots in your move helper
Inspect the candidate block type before assigning it to `--previous`
When a document ID shows up, automatically redirect it to `--parent` in tooling

When it happens

Trigger: Passing a document root ID as `--previous` (sibling anchor) instead of `--parent` (container). The previous block passes the existence check but its type `d` trips this semantic guard.

Common situations: Confusing the destination document's ID as a sibling rather than the parent; copy-pasting a doc ID into `--previous`; building a move script that reused a document ID in the wrong slot.

Related errors

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