What causes "assetPath is not an image referenced by the document" in siyuan-note/siyuan?

Open the document and confirm the image embed exists, then pass exactly the path it references

assetPath is not an image referenced by the document

Error message

assetPath is not an image referenced by the document

What it means

Even a valid assets/ path is rejected unless the resolved document's tree actually references that asset as an image (documentReferencesImage check). This prevents analyzing images that belong to other documents or unreferenced files.

Solutions

Open the document and confirm the image embed exists, then pass exactly the path it references
Re-copy/paste the image into the document so a fresh reference is created
Fetch the correct path via ListDocumentImages instead of hardcoding it

Example fix

// before
PrepareDocumentImage(docID, "assets/other-doc.png")
// after
list, _ := ListDocumentImages(docID)
PrepareDocumentImage(docID, list.Images[0].Path)

Defensive patterns

Strategy: validation

Validate before calling

list, err := ListDocumentImages(documentID)
if err != nil || !containsPath(list, assetPath) { /* not referenced by this document */ }

Try / catch

prepared, err := PrepareDocumentImage(docID, assetPath)
if err != nil && strings.Contains(err.Error(), "not an image referenced") { return userFacingError("pick an image from this document") }

Prevention

Derive assetPath from the target document's image list each time
Refresh captured paths after document edits (references may be deleted)
Match asset filenames exactly, including timestamp/id suffixes

When it happens

Trigger: Calling PrepareDocumentImage with an assets path that exists but is not referenced by documentID, or referencing it only via a non-image embed (e.g. link text rather than an img node).

Common situations: Reusing an image from another document; the reference was deleted from the document after the path was captured; typo in the asset filename so it no longer matches the reference.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

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

Appendix: source

Thrown at kernel/model/assets.go:465

	}
	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")
	}
	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
}

View on GitHub (pinned to 9f775e8a12)