siyuan-note/siyuan · error

unsupported or invalid image: %s

Error message

unsupported or invalid image: %s

What it means

After the MIME check, PrepareModelImage calls image.DecodeConfig to cheaply read the image header. If decoding fails (corrupt file, truncated data, or a format with no registered decoder), it wraps the underlying reason in this error. It distinguishes 'the bytes are not a decodable image' from the earlier format-allowlist errors.

Source

Thrown at kernel/util/openai.go:755

func PrepareModelImage(data []byte, maxBytes, maxPixels, maxEdge int) (PreparedImage, error) {
	if len(data) == 0 {
		return PreparedImage{}, errors.New("image data is empty")
	}
	if maxBytes > 0 && len(data) > maxBytes {
		return PreparedImage{}, fmt.Errorf("image exceeds size limit: %d bytes", maxBytes)
	}
	mimeType := mimetype.Detect(data).String()
	if strings.Contains(mimeType, "svg") || bytes.Contains(bytes.ToLower(data[:min(len(data), 512)]), []byte("<svg")) {
		return PreparedImage{}, errors.New("SVG images are not accepted by multimodal models")
	}
	switch mimeType {
	case "image/gif", "image/jpeg", "image/png", "image/webp":
	default:
		return PreparedImage{}, fmt.Errorf("unsupported image type: %s", mimeType)
	}
	config, _, err := image.DecodeConfig(bytes.NewReader(data))
	if err != nil {
		return PreparedImage{}, errors.New("unsupported or invalid image: " + err.Error())
	}
	if config.Width < 1 || config.Height < 1 || maxPixels > 0 && int64(config.Width)*int64(config.Height) > int64(maxPixels) {
		return PreparedImage{}, fmt.Errorf("image exceeds pixel limit: %d", maxPixels)
	}

	decoded, err := imaging.Decode(bytes.NewReader(data), imaging.AutoOrientation(true))
	if err != nil {
		return PreparedImage{}, errors.New("decode image failed: " + err.Error())
	}
	bounds := decoded.Bounds()
	needsResize := maxEdge > 0 && (bounds.Dx() > maxEdge || bounds.Dy() > maxEdge)
	if !needsResize && bounds.Dx() == config.Width && bounds.Dy() == config.Height && mimeType != "image/gif" {
		return PreparedImage{
			Data:       data,
			MIMEType:   mimeType,
			Width:      bounds.Dx(),
			Height:     bounds.Dy(),
			SourceSize: len(data),

View on GitHub (pinned to 8641553a1f)

Solutions

1. Re-download or re-copy the image from its source — the file is likely corrupt or truncated
2. Open the file in an image viewer to confirm it is valid before sending it to the model
3. Check disk/sync integrity for the asset (possibly re-sync the workspace)
4. Verify the backend links the needed image decoders if you extended supported formats

Example fix

// before: no integrity check
prepared, err := PrepareModelImage(data, maxBytes, maxPixels, maxEdge)
// after: fail fast on truncated files
if fi, e := os.Stat(path); e != nil || fi.Size() == 0 {
    return errors.New("asset missing or empty: " + path)
}
prepared, err := PrepareModelImage(data, maxBytes, maxPixels, maxEdge)

if _, _, err := image.DecodeConfig(bytes.NewReader(data)); err != nil {
    return fmt.Errorf("asset is not a decodable image: %w", err)
}

prepared, err := PrepareModelImage(data, maxBytes, maxPixels, maxEdge)
if err != nil && strings.Contains(err.Error(), "unsupported or invalid image") {
    log.Warnf("asset corrupt, re-fetching: %v", err)
    return reDownloadAsset()
}

When it happens

Trigger: Calling PrepareModelImage with truncated or corrupt image data, a file that passes MIME sniffing but has a broken header, or a format whose Go decoder was not linked into the binary.

Common situations: Partially downloaded assets; files corrupted on disk or in sync; images with valid extensions but garbage content; zero-dimension or otherwise malformed headers.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

• invalid custom emoji image
• unsupported or invalid image:
• decode image failed:
• unsupported custom emoji image format
• invalid video poster: %w

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