Step by Step Guide for n8n SQLite Version Compatibility
Who this is for: Developers and DevOps engineers running n8n in production who need to ensure the bundled SQLite engine matches the n8n version they deploy. For a complete guide on managing SQLite in n8n, including errors, performance, and migration, check out our n8n SQLite pillar guide.
Quick Diagnosis
- n8n 1.30 – 1.34 ships with SQLite 3.40.x
- n8n 1.35 – 1.38 ships with SQLite 3.41.x
- n8n 1.39 + requires SQLite 3.42.x or newer
Run sqlite3 --version inside the n8n container (or SELECT sqlite_version(); in a workflow) and compare it against the matrix below. Mismatches produce errors such as “SQLite version mismatch – required ≥ 3.41.0, found 3.38.5”. Resolve by upgrading the SQLite binary or pinning an n8n version that matches your SQLite build.
Why Compatibility Matters?
n8n stores workflows, execution data, and credentials in a local SQLite file (.n8n/database.sqlite). Each n8n release is compiled against a specific SQLite library version that introduces new SQL features (e.g., generated columns, JSON functions) and deprecates old behaviours. An older runtime SQLite engine cannot satisfy the queries n8n emits, leading to SQL errors like “no such function: json_each”. Newer SQLite builds are generally backward‑compatible, but compile‑time pragmas can cause regressions if the major version diverges. Learn to handle unsupported SQLite features, constraints, and version issues in n8n workflows.
Compatibility Matrix
| n8n Release (SemVer) | Bundled SQLite* | Minimum Required SQLite | Notable SQLite‑dependent Features |
|---|---|---|---|
| 1.30 – 1.34 | 3.40.2 (Docker) | 3.40.0 | Generated columns, improved UPSERT |
| 1.35 – 1.38 | 3.41.0 (Docker) | 3.41.0 | JSON functions (json_each, json_tree) |
| 1.39 – 1.41 | 3.42.0 (Docker) | 3.42.0 | Window‑function enhancements, ALTER TABLE RENAME COLUMN |
| 2.0‑beta (latest) | 3.45.0 (Docker) | 3.45.0 | SQL‑generated primary keys, STRICT tables |
*Docker images embed the SQLite library in the Node.js binary. When running n8n on a host‑installed Node.js, the system SQLite version is used instead.
How to read the matrix
- Bundled SQLite – version shipped with the official
n8nio/n8nDocker image. - Minimum Required SQLite – oldest version that satisfies all queries n8n issues. Anything older triggers a version‑mismatch error.
- Notable Features – new SQLite capabilities n8n relies on starting with that release. Missing these features typically surface as “no such function” errors.
Detecting the SQLite Version Used by n8n
1. From the Docker CLI
docker exec -it <n8n_container_name> sqlite3 --version
Running sqlite3 inside the container guarantees you see the bundled version, not the host’s libsqlite3‑dev.
2. From Within a Workflow (SQL Node)
SELECT sqlite_version() AS version;
Add a Run Query node (type: SQLite) with the statement above, then inspect the output.
3. Programmatically via Node.js
import sqlite3 from 'sqlite3';
const db = new sqlite3.Database(':memory:');
db.get('SELECT sqlite_version() AS v', (err, row) => console.log(row.v));
If this call fails with SQLITE_ERROR: no such function: sqlite_version, you’re using a pre‑3.7 SQLite build, which is unsupported by any current n8n version. Understand foreign key constraints, version compatibility, and unsupported feature issues in n8n SQLite.
Typical Errors Caused by Version Mismatch
| Symptom | Typical Error Message | Root Cause |
|---|---|---|
| Workflow fails on a JSON node | SQLITE_ERROR: no such function: json_extract |
SQLite < 3.41 (no JSON functions) |
| Generated column addition errors | SQLITE_ERROR: near "GENERATED": syntax error |
SQLite < 3.40 |
Window function ROW_NUMBER() not recognized |
SQLITE_ERROR: no such function: row_number |
SQLite < 3.42 |
| Startup aborts with version mismatch | SQLite version mismatch – required ≥ 3.41.0, found 3.38.5 |
n8n expects newer SQLite than installed |
Upgrading or Downgrading SQLite for n8n
A. Use the Official Docker Image (Recommended)
docker pull n8nio/n8n:1.39 docker stop n8n && docker rm n8n docker run -d --name n8n -p 5678:5678 n8nio/n8n:1.39
Never mix a newer n8n image with an older host‑installed SQLite library; the bundled binary will be ignored, leading to unpredictable behaviour.
B. Pin a Specific SQLite Binary (Advanced)
When you must stay on an older n8n release (e.g., custom plugins), replace the SQLite library inside the container.
Dockerfile – base and build tools
FROM n8nio/n8n:1.34 # Install build dependencies RUN apt-get update && apt-get install -y wget build-essential
Dockerfile – download and compile SQLite
# Download SQLite source (v3.45.0)
RUN wget https://www.sqlite.org/2024/sqlite-autoconf-3450000.tar.gz \
&& tar xzf sqlite-autoconf-3450000.tar.gz \
&& cd sqlite-autoconf-3450000 \
&& ./configure --prefix=/usr/local \
&& make && make install
Dockerfile – clean up
# Remove temporary files and apt cache RUN rm -rf /var/lib/apt/lists/* sqlite-autoconf-*
Re‑build and redeploy:
docker build -t custom-n8n:1.34-sqlite3.45 . docker run -d --name n8n -p 5678:5678 custom-n8n:1.34-sqlite3.45
When compiling SQLite yourself, enable SQLITE_ENABLE_JSON1 and SQLITE_ENABLE_FTS5 to keep feature parity with the official builds.
C. Host‑Installed Node.js (Non‑Docker)
sudo apt-get update sudo apt-get install -y sqlite3 libsqlite3-dev # Verify the upgrade sqlite3 --version # should be ≥ required version
Reinstall n8n so the Node.js binary links against the new library.
npm rebuild sqlite3 # forces recompilation against the new lib npm install -g n8n@1.39
Always test in a staging environment first; rebuilding native modules can break other npm packages that depend on SQLite.
Step‑by‑Step: Fixing a Version‑Mismatch Error in Production
- Identify the error – check n8n logs (
docker logs n8n) for the exact version requirement. - Confirm current SQLite version – run one of the detection methods above.
- Match the matrix – locate the n8n release that aligns with your SQLite version.
- Choose a fix
- Upgrade n8n to a release that bundles a newer SQLite (preferred).
- Upgrade SQLite to meet the minimum required version (if you cannot change n8n).
- Pin n8n to an older version that works with your SQLite (last resort).
- Apply the change – redeploy the container or rebuild the binary as shown.
- Validate – re‑run the failing workflow; the error should disappear.
- Document – add a note in your internal run‑book with the matrix snapshot (date‑stamped) to avoid future regressions.
- Explore migration strategies while considering SQLite constraints, compatibility, and feature limitations in n8n.
Best Practices for Long‑Term Compatibility
| Practice | Why It Matters |
|---|---|
Lock n8n version in docker‑compose.yml (e.g., image: n8nio/n8n:1.39) |
Prevents accidental upgrades that could out‑date your SQLite library. |
Run SELECT sqlite_version(); on every deployment |
Guarantees the runtime matches the matrix; early detection reduces downtime. |
| Version‑control the compatibility matrix | Provides an auditable reference for auditors and future developers. |
Enable SQLite’s PRAGMA journal_mode=WAL; |
Improves concurrency and reduces lock‑related errors that can be confused with version mismatches. |
| Monitor n8n release notes | New releases may bump the minimum SQLite version; staying informed avoids surprise breakages. |
Next Steps / Related Topics
- Upgrade your n8n instance safely – see the child page “n8n version upgrade checklist” for a full deployment pipeline.
- Understanding SQLite pragmas used by n8n – deep dive into performance‑tuning options (
journal_mode,synchronous,cache_size).
All instructions are production‑grade; always test changes in a staging environment before applying to live workflows.
