siyuan-note/siyuan · error

list document images failed: %w

Error message

list document images failed: %w

What it means

Returned by ListDocumentImages when DocImageAssets(rootID) fails. DocImageAssets loads the document's .sy tree via LoadTreeByBlockID and walks the AST collecting NodeImage link destinations; the %w wraps the underlying tree-load or walk error. This is an infrastructure/data error, not a validation error.

Source

Thrown at kernel/model/assets.go:364

	return errors.As(err, &target)
}

func markImageExecutionUnknown(err error) error {
	if err == nil || IsImageExecutionUnknown(err) {
		return err
	}
	return &imageExecutionUnknownError{err: err}
}

// ListDocumentImages 返回文档引用的本地图片，供智能体工具和编辑器功能复用。
func ListDocumentImages(documentID string) (DocumentImageList, error) {
	bt, err := resolveMultimodalDocument(documentID)
	if err != nil {
		return DocumentImageList{}, err
	}
	paths, err := DocImageAssets(bt.RootID)
	if err != nil {
		return DocumentImageList{}, fmt.Errorf("list document images failed: %w", err)
	}
	refs := make([]ImageArtifactRef, 0, len(paths))
	seen := map[string]bool{}
	for _, assetPath := range paths {
		if !strings.HasPrefix(AssetPathWithoutQuery(assetPath), "assets/") || seen[assetPath] {
			continue
		}
		seen[assetPath] = true
		refs = append(refs, ImageArtifactRef{Kind: "image", Path: assetPath, DocumentID: bt.RootID})
	}
	return DocumentImageList{DocumentID: bt.RootID, Images: refs}, nil
}

// PrepareDocumentImage 校验并读取文档实际引用的本地资源图片，供当前模型直接接收图片输入。
func PrepareDocumentImage(documentID, assetPath string) (PreparedDocumentImage, error) {
	assetPath = strings.TrimSpace(assetPath)
	if assetPath == "" {
		return PreparedDocumentImage{}, errors.New("assetPath is required for analyze")

View on GitHub (pinned to 251596fc0d)

Solutions

1. Run a kernel data-index rebuild / notebook reindex so blocktree.db matches on-disk .sy files.
2. Verify the .sy file exists on disk under <data>/<boxID>/<path> for the resolved rootID.
3. Check the kernel log (the wrapped error names the exact tree-load failure) and address that root cause.
4. If the document was legitimately deleted, treat the error as a not-found and stop listing it.

Example fix

// before
list, err := model.ListDocumentImages(docID)
if err != nil { return err }

// after — distinguish index/IO failure from empty result
list, err := model.ListDocumentImages(docID)
if err != nil {
    logging.LogErrorf("list images for %s: %s", docID, err)
    return err // surface to caller; do not retry in a tight loop
}
_ = list

// Validate the document still exists in the blocktree index first.
bt := treenode.GetBlockTree(strings.TrimSpace(documentID))
if bt == nil {
    return errors.New("document not found")
}
// Then call; DocImageAssets may still fail on disk parse — handle as try-catch.

list, err := model.ListDocumentImages(documentID)
if err != nil {
    // wrapped error — log the root cause, do not auto-retry in a loop
    logging.LogErrorf("list document images %s: %s", documentID, err)
    return err
}

When it happens

Trigger: Calling ListDocumentImages with a documentID that resolves to a block tree whose .sy file is missing, corrupt, unreadable on disk, or fails to parse via LoadTreeByBlockID. The documentID itself passed resolveMultimodalDocument (so it exists in blocktree.db), but the on-disk tree load failed.

Common situations: The blocktree index is stale (block deleted but blocktree.db not yet updated), the .sy file was removed manually or by sync conflict, the file is locked by another process, or the data directory was moved while the kernel was running.

Related errors

• read image failed: %w
• read custom emoji response failed: %w
• write data [%s] failed: %s
• assetPath is required for analyze
• only local assets/... images are supported

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