siyuan-note/siyuan · error

image exceeds pixel limit

Error message

image exceeds pixel limit: %d

What it means

Thrown when an image decodes structurally but its pixel dimensions fail the configured constraint in kernel/util/openai.go: config.Width or config.Height is less than 1, or width*height exceeds the maxPixels budget. The %d value in the message is the pixel budget that was exceeded (0 means no pixel cap was set, so a <1 dimension triggered it).

Solutions

1. Resize or downscale the image so width*height is within the limit before sending it
2. Increase the maxPixels configuration value in the AI image settings if the budget is too small
3. If the message shows limit 0 with a genuinely broken image, replace the corrupt source file
4. Crop the image to the region of interest to cut pixel count

Example fix

// before
img, err := prepareImage(data, mime, 4096*4096, 2048, 8<<20)
// after: pre-check pixels and downscale first
if w*h > 4096*4096 {
    data, _ = downscaleToWithinPixelBudget(data, 4096*4096)
}
img, err := prepareImage(data, mime, 4096*4096, 2048, 8<<20)

cfg, _, err := image.DecodeConfig(bytes.NewReader(data))
if err != nil { return err }
if cfg.Width < 1 || cfg.Height < 1 { return errors.New("zero-dimension image") }
if int64(cfg.Width)*int64(cfg.Height) > 4096*4096 {
    return errors.New("image too large; downscale first")
}

When it happens

Trigger: Calling the image preparation function with an image whose width*height is greater than maxPixels, or with a decoded 0-width/0-height image while maxPixels > 0.

Common situations: Users paste 50-megapixel camera photos or 8K screenshots; a caller passes maxPixels=0 intending 'unlimited' but the image also has zero dimensions; a tightly configured maxPixels rejects images that worked before the limit was tightened.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

• generated image exceeds size limit
• generated image is invalid
• prepared image exceeds size limit
• BASE64_IMAGE_SIZE_LIMIT
• decode image failed

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

Appendix: source

Thrown at kernel/util/openai.go:782

	}
	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),
		}, nil
	}
	if needsResize {

View on GitHub (pinned to 9f775e8a12)