sort target document [%s] is not a sibling of the new docume

Error message

sort target document [%s] is not a sibling of the new document

What it means

When a sortTargetID is given, CreateDocByMd verifies the target is a sortable document, belongs to the same notebook (target.BoxID == boxID), and sits in the same parent directory as the new document's path (path.Dir equality). Failing any check returns fmt.Errorf("sort target document [%s] is not a sibling of the new document").

Source

Thrown at kernel/model/file.go:1295

var createDocLock = sync.Mutex{}

func CreateDocByMd(boxID, p, title, md string, sorts []string, arg map[string]any) (tree *parse.Tree, err error) {
	createDocLock.Lock()
	defer createDocLock.Unlock()

	box, err := getOpenedBox(boxID)
	if nil != err {
		return
	}
	sortTargetID, _ := arg["sortTargetID"].(string)
	sortPosition, _ := arg["sortPosition"].(string)
	if "" != sortTargetID {
		if "before" != sortPosition && "after" != sortPosition {
			return nil, fmt.Errorf("invalid sort position [%s]", sortPosition)
		}
		target := treenode.GetBlockTree(sortTargetID)
		if !isSortableDocument(target) || target.BoxID != boxID || path.Dir(target.Path) != path.Dir(p) {
			return nil, fmt.Errorf("sort target document [%s] is not a sibling of the new document", sortTargetID)
		}
	} else if "" != sortPosition {
		return nil, errors.New("sort target ID is required when sort position is specified")
	}

	luteEngine := util.NewLute()
	luteEngine.SetHTMLTag2TextMark(true)
	dom := luteEngine.Md2BlockDOM(md, false)
	tree, err = createDoc(box.ID, p, title, dom, false)
	if err != nil {
		return
	}

	FlushTxQueue()
	if "" != sortTargetID {
		if _, sortErr := ReorderDocs([]string{tree.ID}, sortTargetID, sortPosition); nil != sortErr {
			logging.LogErrorf("reorder created document [%s] failed: %s", tree.ID, sortErr)
			box.setSortByConf(path.Dir(tree.Path), tree.ID)

View on GitHub (pinned to 8641553a1f)

Solutions

Ensure sortTargetID refers to an existing document in the same notebook and same parent folder as the new document's path.
Re-fetch the target document's current ID/path after any move/rename before creating relative to it.
Only pass document-level block IDs (retrieved from the doc tree), never arbitrary block IDs.
Fall back to creating without sortTargetID when sibling placement cannot be guaranteed.

Example fix

// before
createDocWithMd({notebook: boxA, path, markdown, sortTargetID: docFromBoxB});
// after
if (target.boxID === boxA && path.dirname(target.path) === path.dirname(newPath)) {
  createDocWithMd({notebook: boxA, path, markdown, sortTargetID: target.id});
}

Defensive patterns

Strategy: validation

Validate before calling

const target = await getBlockTree(sortTargetID);
const ok = target && target.isDocument && target.boxID === notebook &&
  dirname(target.path) === dirname(newDocPath);
if (!ok) { delete payload.sortTargetID; delete payload.sortPosition; }

Type guard

function isSortableSiblingTarget(t, boxId, newPath) {
  return Boolean(t) && t.isDocument === true && t.boxID === boxId &&
    dirname(t.path) === dirname(newPath);
}

Try / catch

try {
  await createDocWithMd(payload);
} catch (e) {
  if (String(e.msg).includes('not a sibling')) {
    delete payload.sortTargetID;
    await createDocWithMd(payload); // create without relative placement
  }
}

Prevention

Re-resolve target document IDs right before creating relative to them
Only pass document IDs from the same notebook and parent folder
Fall back to non-positional creation when the target cannot be verified

When it happens

Trigger: Calling CreateDocByMd with sortTargetID pointing to a block/document that is missing from the block tree (isSortableDocument false), lives in another notebook, or resides under a different parent path than the new document.

Common situations: Stale target ID after the target document was moved or deleted; cross-notebook drag operations passing a target from another box; passing a non-document block ID (e.g. a paragraph) as sortTargetID.

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@8641553a1f (2026-09-11). Data as JSON: /api/errors/04a7c7eea7d7689b. Report an issue: GitHub.