{"id":3061,"date":"2026-11-19T12:19:39","date_gmt":"2026-11-19T12:19:39","guid":{"rendered":"https:\/\/hostry.com\/blog\/?p=3061"},"modified":"2026-11-19T12:19:40","modified_gmt":"2026-11-19T12:19:40","slug":"n8n-3-upgrade-self-hosted","status":"publish","type":"post","link":"https:\/\/hostry.com\/blog\/n8n-3-upgrade-self-hosted\/","title":{"rendered":"n8n 3.0 Upgrade on a VPS: Back Up So the Restore Actually Works"},"content":{"rendered":"\n<figure class=\"wp-block-image size-full\"><img loading=\"lazy\" decoding=\"async\" width=\"1200\" height=\"675\" src=\"https:\/\/hostry.com\/blog\/wp-content\/uploads\/2026\/11\/n8n-3-upgrade-self-hosted-cover.webp\" alt=\"n8n 3.0 upgrade on a VPS: a backup restored on a second server and checked before the one-way move\" class=\"wp-image-3058\" srcset=\"https:\/\/hostry.com\/blog\/wp-content\/uploads\/2026\/11\/n8n-3-upgrade-self-hosted-cover.webp 1200w, https:\/\/hostry.com\/blog\/wp-content\/uploads\/2026\/11\/n8n-3-upgrade-self-hosted-cover-300x169.webp 300w, https:\/\/hostry.com\/blog\/wp-content\/uploads\/2026\/11\/n8n-3-upgrade-self-hosted-cover-1024x576.webp 1024w, https:\/\/hostry.com\/blog\/wp-content\/uploads\/2026\/11\/n8n-3-upgrade-self-hosted-cover-450x253.webp 450w, https:\/\/hostry.com\/blog\/wp-content\/uploads\/2026\/11\/n8n-3-upgrade-self-hosted-cover-768x432.webp 768w\" sizes=\"auto, (max-width: 1200px) 100vw, 1200px\" \/><\/figure>\n\n\n\n<pre class=\"wp-block-preformatted\" style=\"font-size:14px\"><em><strong>You run self-hosted n8n 2.x on a VPS, and n8n calls the n8n 3.0 upgrade one way. Stable is due in early December, and the route back to 2.x is a backup taken before the first 3.x start. On n8n 2.48.6 with the default SQLite database, a copy of database.sqlite alone restored an empty instance, so back up with sqlite3 .backup plus ~\/.n8n\/config and prove the restore first.<\/strong><\/em><\/pre>\n\n\n\n<p class=\"wp-block-paragraph\">Scope: the SQLite backup, the key behaviour and the restore drill come from n8n 2.48.6 installed from npm, with Node.js 24.22.3 as the runtime and Ubuntu 24.04.5 as the OS. Docker and everything about 3.x follow n8n&#8217;s docs and announcement and were not run, since npm carries no 3.x package and no container was started.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\" style=\"font-size:14px\"><strong>Preparation, on 2.x<\/strong><\/p>\n\n\n\n<ol class=\"wp-block-list\"><li><strong><a href=\"#what-changes\">Check what you run<\/a><\/strong>: <code>n8n --version<\/code>, plus the Node.js version of the service on an npm install. The Migration Report needs 2.39 or later; the npm package of 2.48.6 needs Node.js 24.<\/li><li><strong><a href=\"#key\">Find the encryption key<\/a><\/strong> in <span class=\"highlighted\">~\/.n8n\/config<\/span> and keep a copy off the server.<\/li><li><strong><a href=\"#backup\">Back up the database in a form that restores<\/a><\/strong>: <code>sqlite3 .backup<\/code> plus <code>config<\/code>, or the whole <code>.n8n<\/code> folder with n8n stopped.<\/li><li><strong><a href=\"#npm\">On npm, move to Docker on the same 2.x version<\/a><\/strong>, with the data folder owned by uid 1000 and the service&#8217;s environment carried over.<\/li><li><strong><a href=\"#what-changes\">Update to the latest 2.x and work through the Migration Report<\/a><\/strong> until nothing blocks the upgrade.<\/li><\/ol>\n\n\n\n<p class=\"wp-block-paragraph\" style=\"font-size:14px\"><strong>Staging trial<\/strong><\/p>\n\n\n\n<ol class=\"wp-block-list\" start=\"6\"><li><strong><a href=\"#restore\">Prove the restore<\/a><\/strong> on a separate VPS: owner login, workflow count, and one workflow that uses a credential. Repeat it after every version change, the Docker move included.<\/li><li><strong><a href=\"#upgrade-day\">Upgrade staging to a pinned 3.x tag<\/a><\/strong> and let it run a week of normal workflows.<\/li><\/ol>\n\n\n\n<p class=\"wp-block-paragraph\" style=\"font-size:14px\"><strong>Production cutover<\/strong><\/p>\n\n\n\n<ol class=\"wp-block-list\" start=\"8\"><li><strong><a href=\"#upgrade-day\">Stop, back up, start the same pinned 3.x tag<\/a><\/strong>, run the drill checks, and keep the 2.x copy for a week.<\/li><\/ol>\n\n\n\n<h2 class=\"wp-block-heading\" id=\"what-changes\">What the n8n 3.0 upgrade changes, and when<\/h2>\n\n\n\n<p class=\"wp-block-paragraph\">n8n 3.0 makes Docker the only supported way to self-host, changes several defaults and turns on encryption key rotation, and there is no downgrade path. The <strong><a href=\"https:\/\/community.n8n.io\/t\/announcing-n8n-version-3-0\/324016\" target=\"_blank\" rel=\"noopener\">n8n 3.0 announcement<\/a><\/strong> of October 23, 2026 set the beta for October 27 and the stable 3.x release for early December, with no day given. Support for 1.x ends on December 31, 2026. For a year after 3.x stable, 2.x still gets security fixes and fixes for critical bugs. On direction the post leaves no room: &#8220;There&#8217;s no going back to 2.x afterwards.&#8221;<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">On a single VPS, waiting on 2.x for the first 3.x point release is the sensible default. The fixes keep coming for a year, so December sets no deadline.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">All n8n 3.0 breaking changes are listed on the <strong><a href=\"https:\/\/docs.n8n.io\/changelog\/v30-breaking-changes\/\" target=\"_blank\" rel=\"noopener\">v3.0 breaking changes page<\/a><\/strong>, starting with the end of support for installing with npm or running <code>npx n8n<\/code>. Three more matter on a small VPS. Code node tasks time out after 60 seconds by default instead of 300; the <strong><a href=\"https:\/\/hostry.com\/blog\/n8n-out-of-memory-vps\/\">guide to n8n memory and timeout failures on a VPS<\/a><\/strong> shows how long runs end. On first start 3.0 moves <span class=\"highlighted\">~\/.n8n\/binaryData<\/span> to <span class=\"highlighted\">~\/.n8n\/storage<\/span>; a fresh 2.48.6 install already uses <code>storage<\/code>, as the listing below shows, while older installs still have <code>binaryData<\/code>. And 100.64.0.0\/10 joins the default SSRF block list, which affects workflows that call hosts on a Tailscale network.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">The <strong><a href=\"https:\/\/docs.n8n.io\/hosting\/securing\/encryption-key-rotation\/\" target=\"_blank\" rel=\"noopener\">encryption key rotation docs<\/a><\/strong> say 3.0 turns rotation on for you and that &#8220;Older versions of n8n can&#8217;t read this format,&#8221; so after 3.x has written data, only the pre-upgrade backup takes you back to 2.x.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">The announcement&#8217;s first step is to update to the latest 2.x and open <strong>Settings &gt; Migration Report<\/strong>, available from 2.39. It lists workflow issues and instance issues, each with an impact level; anything marked <span class=\"highlighted\">Upgrade blocked<\/span> has to be fixed on 2.x. On the npm install, the report&#8217;s instance results included this line: &#8220;This instance appears to run outside a container (e.g. installed via npm).&#8221;<\/p>\n\n\n\n<figure class=\"wp-block-image size-large\"><img loading=\"lazy\" decoding=\"async\" width=\"1200\" height=\"675\" src=\"https:\/\/hostry.com\/blog\/wp-content\/uploads\/2026\/11\/n8n-3-upgrade-self-hosted-backup-and-key.webp\" alt=\"A sealed backup box and its key tag placed in a lockbox next to a one-way turnstile in a server room\" class=\"wp-image-3053\" srcset=\"https:\/\/hostry.com\/blog\/wp-content\/uploads\/2026\/11\/n8n-3-upgrade-self-hosted-backup-and-key.webp 1200w, https:\/\/hostry.com\/blog\/wp-content\/uploads\/2026\/11\/n8n-3-upgrade-self-hosted-backup-and-key-300x169.webp 300w, https:\/\/hostry.com\/blog\/wp-content\/uploads\/2026\/11\/n8n-3-upgrade-self-hosted-backup-and-key-1024x576.webp 1024w, https:\/\/hostry.com\/blog\/wp-content\/uploads\/2026\/11\/n8n-3-upgrade-self-hosted-backup-and-key-450x253.webp 450w, https:\/\/hostry.com\/blog\/wp-content\/uploads\/2026\/11\/n8n-3-upgrade-self-hosted-backup-and-key-768x432.webp 768w\" sizes=\"auto, (max-width: 1200px) 100vw, 1200px\" \/><\/figure>\n\n\n\n<h2 class=\"wp-block-heading\" id=\"key\">Where the n8n encryption key lives<\/h2>\n\n\n\n<p class=\"wp-block-paragraph\">The n8n encryption key sits in <span class=\"highlighted\">~\/.n8n\/config<\/span>, in the home folder of the user n8n runs as, as a small JSON file with one <code>encryptionKey<\/code> field. If <code>N8N_ENCRYPTION_KEY<\/code> is not set, n8n generates a random key on the first start and saves it there with mode 600. In the official image the same file ends up at <span class=\"highlighted\">\/home\/node\/.n8n\/config<\/span> on the data volume. A fresh 2.48.6 folder:<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code>No encryption key found - Auto-generating and saving to: \/opt\/n8n3-lab\/n8n3-home-a\/.n8n\/config\n\n~\/.n8n:\n-rw------- 1 root root      56 config\n-rw-r--r-- 1 root root 2469888 database.sqlite\n-rw-r--r-- 1 root root   32768 database.sqlite-shm\n-rw-r--r-- 1 root root 4202432 database.sqlite-wal\n-rw-r--r-- 1 root root     530 n8nEventLog.log\ndrwxr-xr-x 2 root root    4096 nodes\ndrwxr-xr-x 2 root root    4096 storage<\/code><\/pre>\n\n\n\n<p class=\"wp-block-paragraph\">Every credential in the database is encrypted with that key, and nothing else can replace it. Copy the file into a password manager or a vault that does not live on the same VPS.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">Setting the key in the environment as well does not give either source priority. When <code>N8N_ENCRYPTION_KEY<\/code> differs from the file, <code>n8n start<\/code> and the CLI commands, exports included, exit with code 1, as n8n&#8217;s breaking-changes notes for 1.25.0 announced for the main instance (lab path in the message):<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code>Error: Failed to load command \"start\"\nUserError: Mismatching encryption keys. The encryption key in the settings file \/opt\/n8n3-lab\/n8n3-k1\/.n8n\/config does not match the N8N_ENCRYPTION_KEY env var. Please make sure both keys match. More information: https:\/\/docs.n8n.io\/deploy\/host-n8n\/configure-n8n\/basic-configuration\/configuration-examples\/set-a-custom-encryption-key\nexit=1<\/code><\/pre>\n\n\n\n<p class=\"wp-block-paragraph\">With only the variable set, 2.48.6 writes its value into <span class=\"highlighted\">~\/.n8n\/config<\/span> without a log line. From then on both places hold the key and both have to stay identical, which matters when someone later edits a systemd unit or a compose file. Queue mode runs on PostgreSQL and is out of scope here; the <strong><a href=\"https:\/\/hostry.com\/blog\/n8n-queue-mode-workers-not-picking-up-jobs\/\">queue-mode troubleshooting post<\/a><\/strong> covers the worker side.<\/p>\n\n\n\n<aside class=\"hostry-author-note\" style=\"margin:26px 0;padding:16px 20px 14px;background:#fbf7ef;border-left:3px solid #eea416;border-radius:0 10px 10px 0;font-size:15px;line-height:1.6;color:#2b2f3a\">\n<div style=\"font-size:11px;font-weight:700;letter-spacing:.08em;text-transform:uppercase;color:#b07a06;margin:0 0 6px\">From the engineer<\/div>\n<p style=\"margin:0 0 12px\">Keep the config file with the database, in the same backup and the same place. A database without its key is worthless, and the key alone tells nobody which database it belongs to.<\/p>\n<div style=\"display:flex;align-items:center;gap:10px;font-size:13px;color:#5b6170\"><span style=\"display:inline-flex;align-items:center;justify-content:center;width:30px;height:30px;border-radius:50%;background:#11235e;color:#fff;font-size:12px;font-weight:700;flex:none\">SY<\/span><span><strong style=\"color:#11235e\">Stas Yantselovskiy<\/strong> \u00b7 System administrator &amp; DevOps engineer, Hostry<\/span><\/div>\n<\/aside>\n\n\n\n<h2 class=\"wp-block-heading\" id=\"backup\">Back up n8n&#8217;s SQLite database the way it restores<\/h2>\n\n\n\n<p class=\"wp-block-paragraph\">n8n 2.48.6 runs SQLite in WAL mode (<code>PRAGMA journal_mode<\/code> returns <code>wal<\/code>), so new writes land in <span class=\"highlighted\">database.sqlite-wal<\/span> and reach <span class=\"highlighted\">database.sqlite<\/span> only at a checkpoint. After the lab created an owner, a credential and a workflow, the main file still had its old timestamp and the 4.2 MB <code>-wal<\/code> held all of it. A backup therefore needs <code>sqlite3 .backup<\/code>, or the whole folder copied with n8n stopped; the main file alone missed everything.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">Each copy below was restored next to the original <code>config<\/code> and checked for the owner login and for the one workflow and one credential the lab had created:<\/p>\n\n\n\n<figure class=\"wp-block-table\"><table><thead><tr><th>Method<\/th><th>n8n at copy time<\/th><th>Owner login<\/th><th>Workflows \/ credentials<\/th><\/tr><\/thead><tbody><tr><td><code>database.sqlite<\/code> only (b1)<\/td><td>running<\/td><td>no, setup screen<\/td><td>0 \/ 0<\/td><\/tr><tr><td><code>database.sqlite<\/code> only (b5)<\/td><td>stopped with SIGTERM<\/td><td>no, setup screen<\/td><td>0 \/ 0<\/td><\/tr><tr><td>main file + <code>-wal<\/code> + <code>-shm<\/code> (b2)<\/td><td>running<\/td><td>yes<\/td><td>1 \/ 1<\/td><\/tr><tr><td><code>sqlite3 .backup<\/code> (b3)<\/td><td>running<\/td><td>yes<\/td><td>1 \/ 1<\/td><\/tr><tr><td>whole <code>.n8n<\/code> folder, <code>cp -a<\/code><\/td><td>stopped<\/td><td>yes<\/td><td>1 \/ 1<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n<pre class=\"wp-block-code\"><code>== b1-cp-main:        ok  users=1 workflows=0 credentials=0 migrations=307\n== b2-cp-all:         ok  users=1 workflows=1 credentials=1 migrations=344\n== b3-sqlite-backup:  ok  users=1 workflows=1 credentials=1 migrations=344\n== live:                  users=1 workflows=1 credentials=1\n\nstop: kill -TERM &lt;n8n start&gt; -&gt; \"Stopping n8n...\" stopped after 9.3 s, exit 0\nafter clean stop: database.sqlite 2469888 (12:56), database.sqlite-wal 4202432 still present\n== b5-cp-main-after-stop: ok  workflows=0 credentials=0 migrations=307 owner email=&lt;NULL&gt;<\/code><\/pre>\n\n\n\n<p class=\"wp-block-paragraph\">The <code>ok<\/code> in each line is <code>PRAGMA integrity_check<\/code>, and it passed for the useless copies too. The stop made no difference because the WAL was still un-checkpointed afterwards, which is why the familiar habit of stopping n8n and copying the .sqlite file can produce an empty instance. The live three-file copy (b2) worked here, but that is an observation from one run, not a guarantee; take the folder with n8n stopped.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">The online backup needs no downtime and took 0.01 s on the 2.8 MB lab database. Run it as the user n8n runs as. The paths here are examples; swap in your own:<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code>sudo apt install sqlite3\nmkdir -p -m 700 ~\/n8n-backup\nsqlite3 ~\/.n8n\/database.sqlite \".backup $HOME\/n8n-backup\/database.sqlite\"\ncp -p ~\/.n8n\/config ~\/n8n-backup\/<\/code><\/pre>\n\n\n\n<p class=\"wp-block-paragraph\">Since <code>integrity_check<\/code> cannot tell a stale copy from a good one, count rows instead. Each number should match what the editor shows; zero owners with an email means the copy will open on the setup screen.<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code>sqlite3 ~\/n8n-backup\/database.sqlite \\\n  \"select count(*) from workflow_entity;\" \\\n  \"select count(*) from credentials_entity;\" \\\n  \"select count(*) from \\\"user\\\" where email is not null;\"<\/code><\/pre>\n\n\n\n<p class=\"wp-block-paragraph\">For the folder method, stop n8n and run <code>cp -a ~\/.n8n ~\/n8n-backup\/n8n-folder<\/code>. That copy also takes <code>storage\/<\/code> with any binary data, and <code>nodes\/<\/code> if you installed community nodes; the <code>.backup<\/code> method covers only the database and <code>config<\/code>. Then copy <code>~\/n8n-backup<\/code> to another machine, for example the staging VPS (replace the host with yours):<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code>scp -rp ~\/n8n-backup admin@staging.example.com:<\/code><\/pre>\n\n\n\n<figure class=\"wp-block-image size-large\"><img loading=\"lazy\" decoding=\"async\" width=\"1200\" height=\"800\" src=\"https:\/\/hostry.com\/blog\/wp-content\/uploads\/2026\/11\/n8n-3-upgrade-self-hosted-what-restores.webp\" alt=\"Which n8n SQLite backups restore: database.sqlite alone gives an empty n8n, while sqlite3 .backup or the stopped folder with config brings back the owner, workflows and credentials\" class=\"wp-image-3050\" srcset=\"https:\/\/hostry.com\/blog\/wp-content\/uploads\/2026\/11\/n8n-3-upgrade-self-hosted-what-restores.webp 1200w, https:\/\/hostry.com\/blog\/wp-content\/uploads\/2026\/11\/n8n-3-upgrade-self-hosted-what-restores-300x200.webp 300w, https:\/\/hostry.com\/blog\/wp-content\/uploads\/2026\/11\/n8n-3-upgrade-self-hosted-what-restores-1024x683.webp 1024w, https:\/\/hostry.com\/blog\/wp-content\/uploads\/2026\/11\/n8n-3-upgrade-self-hosted-what-restores-450x300.webp 450w, https:\/\/hostry.com\/blog\/wp-content\/uploads\/2026\/11\/n8n-3-upgrade-self-hosted-what-restores-768x512.webp 768w\" sizes=\"auto, (max-width: 1200px) 100vw, 1200px\" \/><figcaption>What each backup method brought back on n8n 2.48.6 with the original config file.<\/figcaption><\/figure>\n\n\n\n<h3 class=\"wp-block-heading\">CLI exports are a second copy, not the backup<\/h3>\n\n\n\n<p class=\"wp-block-paragraph\">The export commands suit a git history of workflows:<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code>n8n export:workflow --all --output=workflows.json\nn8n export:credentials --all --output=credentials.json\nn8n export:credentials --all --decrypted --output=credentials-decrypted.json<\/code><\/pre>\n\n\n\n<p class=\"wp-block-paragraph\">As a restore source they fell short: an instance rebuilt from them opened on the setup screen, without the owner account. With <code>--decrypted<\/code>, the credentials file holds every secret in plain text, and it was written world-readable:<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code>-rw-r--r-- 1 root root  392 Nov 19 12:58 credentials-decrypted.json<\/code><\/pre>\n\n\n\n<p class=\"wp-block-paragraph\">If a move needs one, delete it right after the import, and never leave it in a web root or a synced folder.<\/p>\n\n\n\n<h2 class=\"wp-block-heading\" id=\"restore\">Prove the restore before you upgrade<\/h2>\n\n\n\n<p class=\"wp-block-paragraph\">A restore counts as proven when the owner can log in, the workflow count matches, and a workflow that uses a credential runs on a machine that has never seen production. Use the same n8n version as production. The restored copy carries every production workflow and credential, so start it where it cannot reach production databases or APIs, and away from the production hostname so no live webhook lands on it.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">A separate staging VPS matched to production in size gives the drill and the later 3.x trial realistic timings; a fresh folder on another machine still proves the backup. A <strong><a href=\"https:\/\/hostry.com\/products\/vps\/\">Hostry Linux VPS<\/a><\/strong> gives full root and resources that scale up or down, from 1 GB RAM up to 32 GB, so the staging box can match production for the trial and shrink afterwards; the entry plan is $6.00\/mo (1 vCPU, NVMe).<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">On an npm staging box, with <code>~\/n8n-backup<\/code> copied over from production:<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code># as the user n8n will run as; ~\/.n8n must not exist yet\n# .backup method:\nmkdir -p -m 700 ~\/.n8n\ncp -p ~\/n8n-backup\/database.sqlite ~\/n8n-backup\/config ~\/.n8n\/\n# or the folder method:\ncp -a ~\/n8n-backup\/n8n-folder ~\/.n8n\n\nn8n start<\/code><\/pre>\n\n\n\n<p class=\"wp-block-paragraph\">Sign in with the production owner&#8217;s email; a setup screen means the copy is stale. When the editor is bound to the loopback address, as in the <code>docker run<\/code> lines below, open a tunnel from your workstation and browse to <code>http:\/\/localhost:5678<\/code>:<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code>ssh -N -L 5678:127.0.0.1:5678 admin@staging.example.com<\/code><\/pre>\n\n\n\n<p class=\"wp-block-paragraph\">For the credential test, use a workflow with a Manual Trigger whose HTTP Request sends the credential to a listener on the staging box&#8217;s 127.0.0.1, as the lab did with a local echo server, and run it from the editor or, with n8n stopped, from the CLI (the ID is the one in the workflow&#8217;s URL). With the key restored, the request arrived with the stored header token:<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code>$ n8n execute --id=nV6KKZT5GXgPZ3Hq\n[...]\nExecution was successful:\n[...]\nexit=0<\/code><\/pre>\n\n\n\n<p class=\"wp-block-paragraph\">Leave <code>config<\/code> out and 2.48.6 refuses to start at all. It first writes a new random key into <span class=\"highlighted\">~\/.n8n\/config<\/span>, then finds that the deployment keys stored in the database cannot be read with it:<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code>No encryption key found - Auto-generating and saving to: \/opt\/n8n3-lab\/n8n3-drill-nokey\/.n8n\/config\nInitializing n8n process\nn8n ready on 127.0.0.1, port 5678\nUnexpectedError: Deployment key 'signing.hmac' cannot be read with this instance encryption key\nExiting due to an error.\nn8n exited before ready (exit status 1)<\/code><\/pre>\n\n\n\n<p class=\"wp-block-paragraph\">The failed start did not touch the database: its <code>deployment_key<\/code> rows were identical before and after. Copying the original <code>config<\/code> over the generated one brought the same folder back, with the owner login, the workflow and a successful run. The generated file looks exactly like a real key file, so a folder backed up after such a start pairs a good database with the wrong key, and nobody notices until the next restore. If a restored n8n exits with that <code>signing.hmac<\/code> line, look for a newer <code>config<\/code> than the database before anything else.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">Rebuilding from exports hides the same mismatch for longer. Encrypted credentials imported into an instance with a different key reported success:<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code>$ n8n import:credentials --input=credentials.json\nNo encryption key found - Auto-generating and saving to: \/opt\/n8n3-lab\/n8n3-imp-encrypted\/.n8n\/config\n[...]\nSuccessfully imported 1 credential.\nexit=0<\/code><\/pre>\n\n\n\n<p class=\"wp-block-paragraph\">The error came only when the workflow ran, as a <code>CredentialDataError<\/code> blaming a different encryption key. After any import, run a workflow that uses the imported credential to confirm it decrypts. The drill validates the backup that a rollback needs; the rollback steps themselves are under <strong><a href=\"#upgrade-day\">upgrade day<\/a><\/strong>.<\/p>\n\n\n\n<aside class=\"hostry-author-note\" style=\"margin:26px 0;padding:16px 20px 14px;background:#fbf7ef;border-left:3px solid #eea416;border-radius:0 10px 10px 0;font-size:15px;line-height:1.6;color:#2b2f3a\">\n<div style=\"font-size:11px;font-weight:700;letter-spacing:.08em;text-transform:uppercase;color:#b07a06;margin:0 0 6px\">From the engineer<\/div>\n<p style=\"margin:0 0 12px\">A backup you have not restored is a guess. Before any one-way upgrade I would restore last night&#8217;s copy on a second server and log in as the owner; if the setup screen appears, the backup is not one.<\/p>\n<div style=\"display:flex;align-items:center;gap:10px;font-size:13px;color:#5b6170\"><span style=\"display:inline-flex;align-items:center;justify-content:center;width:30px;height:30px;border-radius:50%;background:#11235e;color:#fff;font-size:12px;font-weight:700;flex:none\">SY<\/span><span><strong style=\"color:#11235e\">Stas Yantselovskiy<\/strong> \u00b7 System administrator &amp; DevOps engineer, Hostry<\/span><\/div>\n<\/aside>\n\n\n\n<h2 class=\"wp-block-heading\" id=\"npm\">Move n8n from npm to Docker<\/h2>\n\n\n\n<p class=\"wp-block-paragraph\">An npm install cannot take the n8n 3.0 upgrade in place, because on November 19, 2026 the registry has no 3.x n8n at all. Of 1263 published versions none starts with 3, and <code>latest<\/code> and <code>stable<\/code> both point to 2.48.6:<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code>$ npm view n8n dist-tags\n{\n  beta: '2.49.2',\n  rc: '1.123.99',\n  latest: '2.48.6',\n  stable: '2.48.6',\n  next: '2.49.2'\n}\n$ npm view n8n@3.0.0\nnpm error code E404\nnpm error 404 No match found for version 3.0.0\nnpm error 404\nnpm error 404  'n8n@3.0.0' is not in this registry.<\/code><\/pre>\n\n\n\n<p class=\"wp-block-paragraph\">So <code>npm update -g n8n<\/code> keeps you on 2.x, which still gets fixes for a year after 3.x stable. n8n 3.0 no longer supports npm installs, yet nothing breaks in December; the support window becomes your deadline for moving from npm to Docker.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">Staying on npm meanwhile has its own catch. The 2.48.6 package declares <code>{ node: '&gt;=24.0.0' }<\/code>, while Ubuntu 24.04&#8217;s <code>apt install nodejs<\/code> gives 18.19.1 and no npm. With the apt npm 9.2.0, <code>npm install n8n@2.48.6 --package-lock-only<\/code> resolved the package with only <code>EBADENGINE<\/code> warnings and exit code 0 (a full install on Node 18 was not run). The failure shows at start, on Node 22 too:<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code>Your Node.js version 18.19.1 is currently not supported by n8n.\nPlease use a Node.js version that satisfies the following version range: &gt;=24.0.0\nexit=1\n\nYour Node.js version 22.23.4 is currently not supported by n8n.\nPlease use a Node.js version that satisfies the following version range: &gt;=24.0.0\nexit=1<\/code><\/pre>\n\n\n\n<p class=\"wp-block-paragraph\"><code>n8n --version<\/code> printed 2.48.6 and exited 0 under both of those Node versions, so check the service log after any npm update.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">Move to Docker on the version you already run, and take 3.x as a separate step, so a failure has one possible cause. The container side below was not run for this article: the volume layout follows the <strong><a href=\"https:\/\/docs.n8n.io\/hosting\/installation\/docker\/\" target=\"_blank\" rel=\"noopener\">n8n Docker installation docs<\/a><\/strong>, which mount the data at <span class=\"highlighted\">\/home\/node\/.n8n<\/span>, and the image&#8217;s Dockerfile sets <code>USER node<\/code>, a user that community reports put at uid 1000. The folder side was reproduced with npm n8n running as uid 1000.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">First, while the npm service keeps running, install Docker Engine from <strong><a href=\"https:\/\/docs.docker.com\/engine\/install\/ubuntu\/\" target=\"_blank\" rel=\"noopener\">Docker&#8217;s apt repository for Ubuntu<\/a><\/strong> and pull the image, so a slow or failed download never leaves n8n down. Then list the environment the running service uses, from its systemd <code>Environment=<\/code> lines, its env file or, as below, the live process:<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code>sudo docker pull n8nio\/n8n:2.48.6\nsudo cat \/proc\/$(pgrep -f '^n8n start')\/environ | tr '\\0' '\\n' | grep -E '^(N8N_|WEBHOOK_URL|GENERIC_TIMEZONE|DB_)' \\\n  | sed 's\/^\\(N8N_ENCRYPTION_KEY=\\).*\/\\1(hidden)\/'<\/code><\/pre>\n\n\n\n<p class=\"wp-block-paragraph\">Put the settings you need into <span class=\"highlighted\">\/srv\/n8n\/n8n.env<\/span>, one <code>KEY=value<\/code> per line, for <code>--env-file<\/code>, which Docker describes as reading &#8220;a file of environment variables&#8221;. Behind a reverse proxy the one that matters most is <code>N8N_WEBHOOK_URL<\/code>, the base URL for test and production webhooks; n8n&#8217;s endpoint docs list <code>WEBHOOK_URL<\/code> as its deprecated alias since 2.35.0. The key travels inside <code>config<\/code>, so leave <code>N8N_ENCRYPTION_KEY<\/code> out, or make sure it matches the file. <code>\/home\/n8n<\/code> below stands for the home of the account your npm install ran as:<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code>sudo systemctl stop n8n          # or pm2 stop, whatever supervises it\nsudo systemctl disable n8n\nsudo mkdir -p \/srv\/n8n\nsudo cp -a \/home\/n8n\/.n8n \/srv\/n8n\/.n8n\nsudo chown -R 1000:1000 \/srv\/n8n\/.n8n\nsudo docker run -d --name n8n --restart unless-stopped \\\n  -p 127.0.0.1:5678:5678 \\\n  --env-file \/srv\/n8n\/n8n.env \\\n  -v \/srv\/n8n\/.n8n:\/home\/node\/.n8n \\\n  n8nio\/n8n:2.48.6<\/code><\/pre>\n\n\n\n<p class=\"wp-block-paragraph\">Skip the <code>chown<\/code> and the copy stays root-owned, which fails on the first file n8n opens. Run as uid 1000 against such a copy (lab paths):<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code>Error: Failed to load command \"start\"\nError: EACCES: permission denied, open '\/opt\/n8n3-lab\/n8n3-dock\/home\/node\/.n8n\/config'\nexit=1<\/code><\/pre>\n\n\n\n<p class=\"wp-block-paragraph\">After <code>chown -R 1000:1000<\/code> the same folder started as uid 1000, the owner logged in, and the credential decrypted in a workflow run. Run the drill checks on the container before you go further.<\/p>\n\n\n\n<aside class=\"hostry-author-note\" style=\"margin:26px 0;padding:16px 20px 14px;background:#fbf7ef;border-left:3px solid #eea416;border-radius:0 10px 10px 0;font-size:15px;line-height:1.6;color:#2b2f3a\">\n<div style=\"font-size:11px;font-weight:700;letter-spacing:.08em;text-transform:uppercase;color:#b07a06;margin:0 0 6px\">From the engineer<\/div>\n<p style=\"margin:0 0 12px\">If n8n still runs from npm, move it to Docker now, on the same 2.x version, and let it run for a week. Then the upgrade day changes one thing, the image tag, and not the whole way the service runs.<\/p>\n<div style=\"display:flex;align-items:center;gap:10px;font-size:13px;color:#5b6170\"><span style=\"display:inline-flex;align-items:center;justify-content:center;width:30px;height:30px;border-radius:50%;background:#11235e;color:#fff;font-size:12px;font-weight:700;flex:none\">SY<\/span><span><strong style=\"color:#11235e\">Stas Yantselovskiy<\/strong> \u00b7 System administrator &amp; DevOps engineer, Hostry<\/span><\/div>\n<\/aside>\n\n\n\n<h2 class=\"wp-block-heading\" id=\"upgrade-day\">Upgrade day with a pinned 3.x tag<\/h2>\n\n\n\n<p class=\"wp-block-paragraph\">Run the n8n 3.0 upgrade on the staging copy first, as the announcement advises, and give it a week of normal runs before production gets the same steps. On production, stop n8n, take the backup from the stopped folder, copy it off the server, then start an exact 3.x version:<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code>sudo docker stop n8n\nsudo cp -a \/srv\/n8n\/.n8n \/srv\/n8n\/backup-2.48.6\nsudo docker rm n8n\nsudo docker run -d --name n8n --restart unless-stopped \\\n  -p 127.0.0.1:5678:5678 \\\n  --env-file \/srv\/n8n\/n8n.env \\\n  -v \/srv\/n8n\/.n8n:\/home\/node\/.n8n \\\n  n8nio\/n8n:3.x.y\nsudo docker logs -f n8n<\/code><\/pre>\n\n\n\n<p class=\"wp-block-paragraph\">Replace <code>3.x.y<\/code> with the exact stable version from n8n&#8217;s release notes. A moving tag can pull a newer 3.x on the next restart, and then the version you tested is not the one you run. Repeat the drill checks once it is up: owner login, workflow count, one run with a credential.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">A failed 3.x start can already change the schema, so restore the backup folder instead of only switching the tag. A <strong><a href=\"https:\/\/jacar.es\/en\/prepare-self-hosted-n8n-for-n8n-3\/\" target=\"_blank\" rel=\"noopener\">test of a pre-beta 3.0 nightly on PostgreSQL<\/a><\/strong> reported seven migrations applied and two tables dropped in a start that failed; the measurement is theirs and was not reproduced here. The way back:<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code>sudo docker stop n8n &amp;&amp; sudo docker rm n8n\nsudo mv \/srv\/n8n\/.n8n \/srv\/n8n\/failed-3x\nsudo cp -a \/srv\/n8n\/backup-2.48.6 \/srv\/n8n\/.n8n\nsudo docker run -d --name n8n --restart unless-stopped \\\n  -p 127.0.0.1:5678:5678 \\\n  --env-file \/srv\/n8n\/n8n.env \\\n  -v \/srv\/n8n\/.n8n:\/home\/node\/.n8n \\\n  n8nio\/n8n:2.48.6<\/code><\/pre>\n\n\n\n<p class=\"wp-block-paragraph\">Keep <code>backup-2.48.6<\/code> until 3.x has handled a full week of normal traffic. Restoring it loses whatever was created on 3.x after the upgrade, so decide early. Keep the failed folder too, for the bug report.<\/p>\n\n\n\n<figure class=\"wp-block-image size-large\"><img loading=\"lazy\" decoding=\"async\" width=\"1200\" height=\"800\" src=\"https:\/\/hostry.com\/blog\/wp-content\/uploads\/2026\/11\/n8n-3-upgrade-self-hosted-upgrade-order.webp\" alt=\"Order of steps for the n8n 3.0 upgrade on a VPS, from the Migration Report on 2.x to checking workflows on a pinned 3.x tag, with a one-way arrow to the backup\" class=\"wp-image-3051\" srcset=\"https:\/\/hostry.com\/blog\/wp-content\/uploads\/2026\/11\/n8n-3-upgrade-self-hosted-upgrade-order.webp 1200w, https:\/\/hostry.com\/blog\/wp-content\/uploads\/2026\/11\/n8n-3-upgrade-self-hosted-upgrade-order-300x200.webp 300w, https:\/\/hostry.com\/blog\/wp-content\/uploads\/2026\/11\/n8n-3-upgrade-self-hosted-upgrade-order-1024x683.webp 1024w, https:\/\/hostry.com\/blog\/wp-content\/uploads\/2026\/11\/n8n-3-upgrade-self-hosted-upgrade-order-450x300.webp 450w, https:\/\/hostry.com\/blog\/wp-content\/uploads\/2026\/11\/n8n-3-upgrade-self-hosted-upgrade-order-768x512.webp 768w\" sizes=\"auto, (max-width: 1200px) 100vw, 1200px\" \/><figcaption>Upgrade-day order; the only way back is restoring the 2.x backup.<\/figcaption><\/figure>\n<!-- AddThis Advanced Settings generic via filter on the_content --><!-- AddThis Share Buttons generic via filter on the_content -->","protected":false},"excerpt":{"rendered":"<p>The n8n 3.0 upgrade is one way, so the backup is the rollback. On n8n 2.48.6 a copy of database.sqlite alone restored an instance with no owner, workf&#8230;<\/p>\n","protected":false},"author":8,"featured_media":3059,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[1,78,20],"tags":[],"class_list":["post-3061","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-virtual-private-server","category-apps","category-system-admin"],"read_time":12,"_links":{"self":[{"href":"https:\/\/hostry.com\/blog\/wp-json\/wp\/v2\/posts\/3061","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/hostry.com\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/hostry.com\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/hostry.com\/blog\/wp-json\/wp\/v2\/users\/8"}],"replies":[{"embeddable":true,"href":"https:\/\/hostry.com\/blog\/wp-json\/wp\/v2\/comments?post=3061"}],"version-history":[{"count":1,"href":"https:\/\/hostry.com\/blog\/wp-json\/wp\/v2\/posts\/3061\/revisions"}],"predecessor-version":[{"id":3062,"href":"https:\/\/hostry.com\/blog\/wp-json\/wp\/v2\/posts\/3061\/revisions\/3062"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/hostry.com\/blog\/wp-json\/wp\/v2\/media\/3059"}],"wp:attachment":[{"href":"https:\/\/hostry.com\/blog\/wp-json\/wp\/v2\/media?parent=3061"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/hostry.com\/blog\/wp-json\/wp\/v2\/categories?post=3061"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/hostry.com\/blog\/wp-json\/wp\/v2\/tags?post=3061"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}