siyuan-note/siyuan · error

View state value is too large

Error message

View state value is too large

What it means

ViewStateService.validateValue throws this when a single field value serialized to JSON (wrapped in the {values:{field:value},removeKeys:[]} patch envelope) exceeds MAX_PATCH_BYTES (256 KiB). Each individual set()/patch() value must be small enough that the server patch request can always carry it. It is a client-side guard against writes that could never be flushed to kernel storage.

Source

Thrown at app/src/util/viewState.ts:239

                const nextRemoveKeys = [...removeKeys, field];
                if (count > 0 && (count >= MAX_PATCH_ENTRIES ||
                    getPatchByteLength(values, nextRemoveKeys) > MAX_PATCH_BYTES)) {
                    break;
                }
                removeKeys.push(field);
                this.pendingRemovals.delete(field);
                count++;
            }
        }
        if (count === 0) {
            throw new Error("View state patch cannot be split within the storage limits");
        }
        return {values, removeKeys};
    }

    private validateValue(field: string, value: TViewStateValue) {
        if (getPatchByteLength({[field]: value}, []) > MAX_PATCH_BYTES) {
            throw new Error("View state value is too large");
        }
    }

    private scheduleFlush() {
        this.clearFlushTimer();
        this.flushTimer = setTimeout(() => {
            this.flushTimer = undefined;
            this.flush().catch((error) => console.error(error));
        }, this.flushDelay);
    }

    private clearFlushTimer() {
        if (this.flushTimer !== undefined) {
            clearTimeout(this.flushTimer);
            this.flushTimer = undefined;
        }
    }

View on GitHub (pinned to 8641553a1f)

Solutions

1. Reduce the size of the stored value: keep only the minimal UI state (scroll offsets, collapsed flags, IDs), not full content
2. Split the data across multiple fields, or store the large payload elsewhere (kernel file/asset or a dedicated storage API) and keep only a reference key in view state
3. Prune the value before writing (e.g. cap array length, truncate strings, strip redundant properties)
4. If the data legitimately must persist, use a different persistence mechanism such as plugin storage or a custom kernel endpoint instead of view state

Example fix

// before
service.set("layout", entireProtyleSnapshot); // hundreds of KB
// after
service.set("layout", { scroll: snapshot.scroll, zoom: snapshot.zoom }); // keep only small fields

const MAX_PATCH_BYTES = 256 * 1024;
const getPatchByteLength = (values, removeKeys) =>
    new TextEncoder().encode(JSON.stringify({values, removeKeys})).byteLength;
if (getPatchByteLength({[field]: value}, []) > MAX_PATCH_BYTES) {
    throw new Error(`view state value for "${field}" exceeds 256 KiB; split or shrink it`);
}
service.set(field, value);

const isSmallEnough = (field: string, value: unknown): boolean => {
    try {
        return new TextEncoder().encode(
            JSON.stringify({values: {[field]: value}, removeKeys: []})
        ).byteLength <= 256 * 1024;
    } catch {
        return false; // not JSON-serializable
    }
};

When it happens

Trigger: Calling viewStateService.set(field, value) or patch({...}) where JSON.stringify of that one field's value (including the patch envelope overhead) is larger than 256*1024 bytes. Examples: storing a whole Protyle scroll/render snapshot, base64 images, or a large JSON blob in one field.

Common situations: Developers treat view state as a free-form key-value store and stash large documents, serialized editor content, or cached data in it; a field grows over time (e.g. accumulating entries in an array) until it crosses the 256 KiB limit.

Understand the failure class

Background: payload too large / request exceeds maximum size: why libraries cap bytes and how to fix oversize payloads — this error's family across 50 libraries.

Related errors

• View state service has been destroyed
• Unable to create a canvas context for the PDF rectangle anno
• Unable to load English commands: ${response.status}
• Failed to save agent session
• Failed to remove agent session

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