siyuan-note/siyuan · error

only global assets/... images are supported

Error message

only global assets/... images are supported

What it means

PrepareAgentMessageImage only accepts global workspace asset paths under assets/ (after stripping query strings). Paths outside assets/ — absolute paths, URLs, or notebook-relative paths — are rejected because this API reads images from the global workspace data/assets directory.

Source

Thrown at kernel/model/assets.go:486

		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)
	cleanPath := AssetPathWithoutQuery(assetPath)
	if !strings.HasPrefix(cleanPath, "assets/") {
		return PreparedDocumentImage{}, errors.New("only global assets/... images are supported")
	}
	relativePath, absPath, err := ResolveDataAssetPath(cleanPath)
	if err != nil {
		return PreparedDocumentImage{}, err
	}
	if !strings.HasPrefix(relativePath, "assets/") {
		return PreparedDocumentImage{}, errors.New("only global assets/... images are supported")
	}
	if err = EnsureAssetLocal(absPath); err != nil {
		return PreparedDocumentImage{}, err
	}
	data, err := os.ReadFile(absPath)
	if err != nil {
		return PreparedDocumentImage{}, fmt.Errorf("read image failed: %w", err)
	}
	prepared, err := util.PrepareModelImage(
		data, documentImageMaxBytes, documentImageMaxPixels, documentImageMaxEdge,
	)

View on GitHub (pinned to 8641553a1f)

Solutions

1. Pass a workspace-global path of the form assets/<file>
2. First import the image into the workspace assets directory, then pass its assets/ path
3. Convert remote URLs by downloading into assets/ before invoking

Example fix

// before
model.PrepareAgentMessageImage("/home/user/photo.jpg")
// after
assetPath, err := model.ImportFileAsAsset("/home/user/photo.jpg") // → "assets/photo.jpg"
model.PrepareAgentMessageImage(assetPath)

if !strings.HasPrefix(model.AssetPathWithoutQuery(assetPath), "assets/") {
    return errors.New("pass a global workspace asset path like assets/foo.png")
}

func isGlobalAsset(p string) bool {
    return strings.HasPrefix(model.AssetPathWithoutQuery(p), "assets/")
}

prepared, err := model.PrepareAgentMessageImage(assetPath)
if err != nil && strings.Contains(err.Error(), "only global assets") {
    // import the image into assets/ and retry once
}

When it happens

Trigger: Calling PrepareAgentMessageImage with "https://...", "/tmp/x.jpg", "notebook/assets/x.png", or any path not starting with assets/ when the agent processes a user message image.

Common situations: An agent passes an image URL extracted from chat text; caller passes a path relative to a notebook instead of the workspace root; user pastes a full filesystem path.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• only local assets/... images are supported
• wrong layout type
• filter nesting depth exceeds the maximum allowed
• invalid session id
• invalid session data

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