What causes "list document images failed: %w" in siyuan-note/siyuan?

Check kernel logs for the wrapped %w cause to find the underlying failure

list document images failed

Error message

list document images failed: %w

What it means

ListDocumentImages resolves a multimodal document and then enumerates its image assets via DocImageAssets; if that enumeration returns an error it is wrapped as "list document images failed". It indicates the document's image inventory could not be built.

Solutions

Check kernel logs for the wrapped %w cause to find the underlying failure
Rebuild the asset index / reindex the notebook for the affected document
Verify the document .sy file exists and is valid before retrying the API call

Example fix

// caller-side guard before calling
if _, statErr := os.Stat(docPath); statErr != nil { return fmt.Errorf("document missing: %w", statErr) }
paths, err := ListDocumentImages(docID)

Defensive patterns

Strategy: try-catch

Validate before calling

if _, err := loadTreeByBlockID(rootID); err != nil { /* document index invalid, reindex first */ }

Try / catch

list, err := ListDocumentImages(docID)
if err != nil { log.Errorf("document images unavailable: %v", err); return fallbackImageList(docID) }

Prevention

Keep the asset index healthy (reindex after sync conflicts)
Avoid deleting documents while image operations are in flight
Check kernel logs for the wrapped underlying cause

When it happens

Trigger: Calling ListDocumentImage for a document whose RootID asset scan fails, e.g. the underlying document tree cannot be loaded or the asset index query errors inside DocImageAssets.

Common situations: Corrupted or missing .sy file for the document; database/index inconsistency after a failed sync; document deleted between resolution and asset scan.

Understand the failure class

Background: Database query failed: Internal Server Error 500s wrapping SQL, Prisma, and connection failures — what to check first — this error's family across 16 libraries.

Related errors

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

Appendix: source

Thrown at kernel/model/assets.go:437

	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 9f775e8a12)