siyuan-note/siyuan · error

read image failed

Error message

read image failed: %w

What it means

After the reference check succeeds, the image bytes are read from the document's notebook box via ReadAssetBytesInBox; any read failure is wrapped as "read image failed". The file may be missing, unreadable, or fail validation in the box-aware reader.

Solutions

1. Inspect the wrapped %w cause in kernel logs to distinguish not-found vs permission errors
2. Restore the missing asset file or re-insert the image into the document
3. Check filesystem permissions and the box (notebook) directory location, then retry

Example fix

// caller-side guard
if _, err := os.Stat(filepath.Join(boxDir, assetPath)); err != nil { /* re-import image first */ }
prepared, err := PrepareDocumentImage(docID, assetPath)

if _, err := os.Stat(filepath.Join(dataDir, assetPath)); err != nil { /* asset file missing from box */ }

prepared, err := PrepareDocumentImage(docID, assetPath)
if err != nil { var wrapped interface{ Unwrap() error }; if errors.As(err, &wrapped) { log.Errorf("read image: %v", errors.Unwrap(err)) }; return retryAfterReimport(docID, assetPath) }

When it happens

Trigger: Calling PrepareDocumentImage when the referenced asset file was deleted from the box's assets directory, the box path resolution fails, or OS-level read errors occur (permissions, broken symlink).

Common situations: Asset file removed by manual cleanup or a failed sync while the document reference remains; wrong box (notebook) moved or renamed; permission problems on the data directory.

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

• accessing assets in encrypted notebook
• Conf.Language(0)
• path is not a child of assets directory
• path is not under an assets directory
• read master password migration failed

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

Appendix: source

Thrown at kernel/model/assets.go:469

// PrepareDocumentImage 校验并读取文档实际引用的本地资源图片，供当前模型直接接收图片输入。
func PrepareDocumentImage(documentID, assetPath string) (PreparedDocumentImage, error) {
	assetPath = strings.TrimSpace(assetPath)
	if assetPath == "" {
		return PreparedDocumentImage{}, errors.New("assetPath is required for analyze")
	}
	if !strings.HasPrefix(AssetPathWithoutQuery(assetPath), "assets/") {
		return PreparedDocumentImage{}, errors.New("only local assets/... images are supported")
	}
	bt, err := resolveMultimodalDocument(documentID)
	if err != nil {
		return PreparedDocumentImage{}, err
	}
	if !documentReferencesImage(bt.RootID, assetPath) {
		return PreparedDocumentImage{}, errors.New("assetPath is not an image referenced by the document")
	}
	data, err := ReadAssetBytesInBox(bt.BoxID, assetPath)
	if err != nil {
		return PreparedDocumentImage{}, fmt.Errorf("read image failed: %w", err)
	}
	prepared, err := util.PrepareModelImage(
		data, documentImageMaxBytes, documentImageMaxPixels, documentImageMaxEdge,
	)
	if err != nil {
		return PreparedDocumentImage{}, err
	}
	return PreparedDocumentImage{
		Artifact: ImageArtifactRef{Kind: "image", Path: assetPath, DocumentID: bt.RootID},
		Data:     prepared.Data,
		MIMEType: prepared.MIMEType,
		Prepared: prepared,
	}, nil
}

// PrepareAgentMessageImage 校验并读取智能体用户消息引用的全局资源图片。
func PrepareAgentMessageImage(assetPath string) (PreparedDocumentImage, error) {
	assetPath = strings.TrimSpace(assetPath)

View on GitHub (pinned to 9f775e8a12)