SQLite: too many SQL variables (tested)

sqlite3.OperationalError: too many SQL variables fires when a single statement binds more ? placeholders than SQLite's compiled-in limit. We measured the real number on this system by binary search, and it's neither of the two numbers commonly quoted online.

1. The commonly-cited numbers didn't fail at all

Older SQLite docs and most search results quote a default of 999 (pre-3.32, 2020) or 32,766 (3.32+). We tested both directly against a single multi-row INSERT:

999 placeholders: OK
32,766 placeholders: OK
32,768 placeholders: OK

None of these failed. The limit on this box is clearly higher than either commonly-quoted value.

2. Binary-searching the real boundary

We kept doubling, found failure between 100,000 and 500,000, then binary-searched between those two bounds:

lo, hi = 100000, 500000
while lo < hi - 1:
    mid = (lo + hi) // 2
    try: ... bind mid placeholders ...; lo = mid
    except sqlite3.OperationalError: hi = mid
# result: last OK = 250000, first error = 250001
sqlite3.OperationalError: too many SQL variables

Measured: exactly 250,000 on this system (Debian 13, Python 3.13.5's bundled SQLite 3.46.1). This is a known distro-level build choice — several Linux distributions compile SQLite with SQLITE_MAX_VARIABLE_NUMBER raised well above the upstream default specifically because so many ORMs and bulk-insert tools hit the smaller defaults in practice.

3. The fix: don't hardcode a number, batch defensively instead

Since this limit is compile-time and varies by distro, Python version, and SQLite build — not something you can reliably detect in advance without testing it on your actual deployment target — the robust fix is to chunk large bulk inserts into batches well under any plausible limit (a few thousand rows per statement) rather than relying on a single INSERT with tens of thousands of parameters. This also sidesteps building one enormous SQL string in memory.

Frequently asked questions

Is SQLite's bound-variable limit really 999?

Not on this system — we measured it directly and 999 succeeded with no error, as did 32,766. The 999 figure is SQLite's pre-3.32 (2020) default; it hasn't been accurate for current SQLite builds for years.

What's the actual measured limit?

250,000 on this box (Debian 13, SQLite 3.46.1 via Python 3.13.5) — we found this by binary search, confirming 250,000 placeholders succeed and 250,001 fails with 'too many SQL variables'.

Why would the limit be higher than SQLite's own documented default?

SQLITE_MAX_VARIABLE_NUMBER is set at compile time, and several Linux distributions raise it above the upstream default specifically because ORMs and bulk-insert code commonly hit the smaller historical defaults. We measured the distro-shipped value directly rather than assuming a number from docs.

Should I rely on this exact number (250,000) in my own code?

No — we measured it on one specific system; it will differ by OS, distro, and how SQLite was compiled. The reliable approach is batching bulk inserts into chunks well under any plausible limit, which we didn't need to tune precisely to avoid the error entirely.

Does this limit apply per-statement or per-connection?

Per-statement — we tested it with a single INSERT containing many placeholders; it's the count of distinct bound parameters in one prepared statement, not a cumulative count across multiple statements on the same connection.

Written with AI assistance. Measured on 2026-10-03 with Python 3.13.5's built-in sqlite3 module on Debian 13, by binary-searching the exact number of bound (?) placeholders a single INSERT can take before failing. Every number below is a directly measured boundary, not looked up from docs. PlainHeaders is our extension; Python's sqlite3 is built in.