What causes "load created shorthand document [%s] failed: %w" in siyuan-note/siyuan?

Retry after resolving file-system access (check disk space, close processes locking the file, pause antivirus/backup)

load created shorthand document [%s] failed: %w

Error message

load created shorthand document [%s] failed: %w

What it means

verifyShorthandDocPersisted clears write caches and reloads the tree from the filesystem via loadTreeByBlockTree. If that reload returns an error, the failure is wrapped as "load created shorthand document [%s] failed: %w". The document record exists but its .sy content could not be read back, indicating a write/read or parse problem right after creation.

Source

Thrown at kernel/model/shortcuts.go:323

	if err = verifyShorthandDocPersisted(bt, retID); nil != err {
		return
	}
	box.setSortByConf(path.Dir(bt.Path), retID)

	FlushTxQueue()
	PushCreate(box, bt.Path, nil)
	return
}

func verifyShorthandDocPersisted(bt *treenode.BlockTree, expectedID string) (err error) {
	if nil == bt {
		return fmt.Errorf("get block tree by id [%s] failed after create", expectedID)
	}
	// 清除写入缓存，确保从文件系统重新读取并验证文档。
	cache.RemoveTreeDataInBox(expectedID, bt.BoxID)
	persisted, err := loadTreeByBlockTree(bt)
	if nil != err {
		return fmt.Errorf("load created shorthand document [%s] failed: %w", expectedID, err)
	}
	if nil == persisted || persisted.ID != expectedID {
		return fmt.Errorf("verify created shorthand document [%s] failed", expectedID)
	}
	return nil
}

var consumeShorthandsLock = sync.Mutex{}
var shorthandSaveBoxUnavailableNotified bool

func isShorthandSaveBoxAvailable(box *Box) bool {
	return nil != box && !box.Closed && !box.Encrypted && !IsUserGuide(box.ID)
}

func selectShorthandSaveBox(configuredID string, boxes []*Box) *Box {
	if "" != configuredID {
		for _, box := range boxes {
			if nil != box && box.ID == configuredID && isShorthandSaveBoxAvailable(box) {

View on GitHub (pinned to 8641553a1f)

Solutions

Retry after resolving file-system access (check disk space, close processes locking the file, pause antivirus/backup)
Check kernel logs for the wrapped inner error to identify the exact load failure
If the .sy file is corrupt, delete the bad shorthand document and re-capture the shorthand

Example fix

null

Defensive patterns

Strategy: try-catch

Try / catch

if err := verifyShorthandDocPersisted(bt, expectedID); err != nil {
    var wrapped interface{ Unwrap() error }
    if errors.As(err, &inner); strings.HasPrefix(err.Error(), "load created shorthand document") {
        logging.LogErrorf("shorthand doc unreadable: %v", inner) // inspect inner cause
    }
}

Prevention

Check disk space and file locks before bulk shorthand consumption
Exclude the workspace from aggressive antivirus/backup scanners
Verify generated DOM parses to a valid tree before writing the .sy file

When it happens

Trigger: createShorthandDocByDOM registered the block tree entry, but loadTreeByBlockTree fails when re-reading — unreadable or corrupt .sy file, file lock held, or disk I/O error.

Common situations: Antivirus/backup software locking fresh files; disk full so the .sy write was truncated; concurrent sync or move operations touching the same path; parse failure due to malformed generated DOM.

Understand the failure class

Background: "failed to read file", EACCES, ENOENT and "could not read <path>" errors: when a program can't read a file from disk — this error's family across 49 libraries.

Related errors

AI-assisted analysis of siyuan-note/siyuan@8641553a1f (2026-09-11). Data as JSON: /api/errors/1d3ff8d94f8facf5. Report an issue: GitHub.