siyuan-note/siyuan · warning · Base64ImageSizeLimitError

item

Error message

item

What it means

assertBase64ImageItemSize enforces the per-item byte limit (BASE64_IMAGE_ITEM_MAX_BYTES, optionally lowered by maxBytes) for images inserted as base64 data URLs; exceeding it throws Base64ImageSizeLimitError with scope 'item', carrying actual and maximum bytes.

Solutions

1. Use a smaller image (compress/resize before pasting)
2. Insert the image as a file/asset upload instead of inline base64
3. Raise the applicable limit if the product allows (within BASE64_IMAGE_ITEM_MAX_BYTES)
4. Catch isBase64ImageSizeLimitError and show the size limit message to the user

Example fix

// before
createBase64ImageFile(hugeDataUrl);
// after
try { assertBase64ImageItemSize(bytes, maxBytes); createBase64ImageFile(hugeDataUrl); }
catch (e) { if (isBase64ImageSizeLimitError(e)) showMessage(`max ${e.maxBytes} bytes`); }

if (dataUrl.length * 0.75 > BASE64_IMAGE_ITEM_MAX_BYTES) { showMessage("image too large"); return; }

const withinLimit = (bytes: number, max?: number) => bytes <= Math.min(max ?? BASE64_IMAGE_ITEM_MAX_BYTES, BASE64_IMAGE_ITEM_MAX_BYTES);

try { createBase64ImageFile(dataUrl); } catch (e) { if (isBase64ImageSizeLimitError(e)) showMessage(`Image exceeds ${e.maxBytes} byte limit`); }

When it happens

Trigger: Pasting/dropping an image whose base64 payload exceeds the configured per-item limit — e.g. a screenshot or photo of several MB pasted directly into the editor.

Common situations: Pasting large screenshots from clipboard; dropping high-resolution photos; environments/config where the limit was lowered via maxBytes; offline users who can't rely on file-based upload paths.

Understand the failure class

Background: "File too large" / "file size exceeds limit" errors: why libraries cap file sizes and how to fix them — this error's family across 46 libraries.

Related errors

• BASE64_IMAGE_SIZE_LIMIT
• batch
• custom emoji file must not be empty
• generated image exceeds size limit
• generated image is empty

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

Appendix: source

Thrown at app/src/protyle/upload/base64File.ts:26

export type TBase64ImageSizeLimitScope = "item" | "batch";

export class Base64ImageSizeLimitError extends Error {
    readonly code = "BASE64_IMAGE_SIZE_LIMIT";

    constructor(readonly scope: TBase64ImageSizeLimitScope, readonly actualBytes: number, readonly maxBytes: number) {
        super(`Base64 image ${scope} size ${actualBytes} exceeds ${maxBytes} bytes`);
        this.name = "Base64ImageSizeLimitError";
    }
}

export const isBase64ImageSizeLimitError = (error: unknown): error is Base64ImageSizeLimitError =>
    error instanceof Base64ImageSizeLimitError;

export const assertBase64ImageItemSize = (actualBytes: number, maxBytes?: number) => {
    const itemMaxBytes = Math.min(maxBytes ?? BASE64_IMAGE_ITEM_MAX_BYTES, BASE64_IMAGE_ITEM_MAX_BYTES);
    if (actualBytes > itemMaxBytes) {
        throw new Base64ImageSizeLimitError("item", actualBytes, itemMaxBytes);
    }
};

export const addBase64ImageBatchSize = (currentBytes: number, fileBytes: number) => {
    const totalBytes = currentBytes + fileBytes;
    if (totalBytes > BASE64_IMAGE_BATCH_MAX_BYTES) {
        throw new Base64ImageSizeLimitError("batch", totalBytes, BASE64_IMAGE_BATCH_MAX_BYTES);
    }
    return totalBytes;
};

const startsWith = (bytes: Uint8Array, signature: number[]) =>
    signature.every((value, index) => bytes[index] === value);

const detectBase64ImageFormat = (bytes: Uint8Array): IBase64ImageFormat | undefined => {
    if (startsWith(bytes, [0x89, 0x50, 0x4E, 0x47, 0x0D, 0x0A, 0x1A, 0x0A])) {
        return {extension: "png", mime: "image/png"};
    }

View on GitHub (pinned to 9f775e8a12)