tursodatabase/turso · error

Payload size too large for encoding

Error message

Payload size too large for encoding

What it means

JSONB encoding sizes each element payload with a header supporting at most 0xFFFFFFFF bytes (a 32-bit size marker). A single payload larger than 4 GiB cannot be represented, so the header builder panics.

Source

Thrown at core/json/jsonb.rs:904

                    size_bytes[0],
                    size_bytes[1],
                ])
            }

            // Extra large payload (fits in 4 bytes)
            size if size <= 0xFFFFFFFF => {
                let size_bytes = (size as u32).to_be_bytes();
                HeaderFormat::FourBytes([
                    (element_type as u8) | (SIZE_MARKER_32BIT << 4),
                    size_bytes[0],
                    size_bytes[1],
                    size_bytes[2],
                    size_bytes[3],
                ])
            }

            // Payload too large
            _ => panic!("Payload size too large for encoding"),
        }
    }

    fn get_size_bytes(slice: &[u8], start: usize, count: usize) -> Result<&[u8]> {
        match slice.get(start..start + count) {
            Some(bytes) => Ok(bytes),
            None => bail_parse_error!("Failed to read header size"),
        }
    }
}

pub struct ArrayIteratorState {
    cursor: usize,
    end: usize,
    index: usize,
}

pub struct ObjectIteratorState {

View on GitHub (pinned to 0e69fa4af1)

Solutions

1. Keep individual JSON values under 4 GiB; split large content across rows
2. Validate serialized size before inserting or parsing JSONB
3. Store oversized payloads as plain BLOBs outside the JSON document

Example fix

-- before
INSERT INTO events VALUES (json(?)); -- ? is a 5 GiB JSON string -> panic

-- after
-- guard at the application boundary:
-- assert!(value.len() <= 0xFFFF_FFFF, "json value exceeds 4 GiB JSONB limit");
INSERT INTO blobs VALUES (?); -- oversized content as a plain blob

const JSONB_MAX_PAYLOAD: usize = 0xFFFF_FFFF;
fn fits_jsonb(v: &str) -> bool { v.len() <= JSONB_MAX_PAYLOAD }
assert!(fits_jsonb(&json_text), "json value exceeds 4 GiB JSONB limit");

When it happens

Trigger: Storing or parsing a JSON document whose single string/number payload (or container payload) exceeds 4 GiB: json_insert of a giant string, JSONB parsing of a huge document built by concatenating logs or base64 blobs.

Common situations: Event/log blobs accumulated into one JSON value; tests synthesizing huge literals; importing machine-generated JSON without size checks.

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

• buffer not loaded
• OpenRead on pseudo cursor
• Rewind on non-btree/materialized-view cursor
• unexpected cursor type
• Next on non-btree/materialized-view cursor

AI-assisted analysis of tursodatabase/turso@0e69fa4af1 (2026-08-20). Data as JSON: /api/errors/c0fffd153b5c9a89. Report an issue: GitHub.