DEV Community: Ali Ilyas

n8n Docker Setup: Run n8n in a Container Without Losing Your Data (2026)

Ali Ilyas — Fri, 21 Aug 2026 10:34:50 +0000

Originally published at noderecipe.com.

The fastest n8n Docker setup is a single command, and you'll have the editor open at http://localhost:5678 in about two minutes. The part that trips people up comes later — the container restarts, and every workflow is gone. This guide covers the command, then the things that decide whether your instance survives its first update: where n8n actually stores data, which environment variables matter, and how to pin and roll back versions.

No prior Docker experience is assumed. Where a flag matters, I explain what it does rather than asking you to paste it on faith.

Do you want Docker setup, or full self-hosting?

These are two different jobs, and mixing them up wastes an afternoon.

This guide is about the container itself: how the n8n image runs, where it keeps state, how to update it safely, and what to do when Docker misbehaves. It applies whether you're on a laptop or a server.

Putting n8n on the public internet — a domain, HTTPS certificates, a reverse proxy, Postgres, backups, firewall rules — is a separate concern. That's covered step by step in the complete guide to self-hosting n8n.

If you just want n8n running locally to build and test workflows, stay here. If you want a URL your team can reach, read this first, then that.

One practical note if you already know you're heading for a server: everything below runs unchanged on a $5/month VPS, so there's no need to build locally and migrate later. Hetzner (2 GB for about €4.5) and DigitalOcean ($6 for 1 GB) both run this fine, and both hand new accounts enough signup credit to cover the first month or two. Spin one up now and follow along on it — the commands are identical.

What you'll need

Docker installed. On Linux, Docker Engine plus the Compose plugin. On Windows or macOS, Docker Desktop.
About 1 GB of free RAM. n8n is comfortable in 2 GB once you have a few active workflows.
A terminal. Every command below is copy-pasteable.

Verify Docker is working before going further:

docker --version
docker compose version

If the second command errors, you have an older standalone docker-compose binary. The commands still work — write them as docker-compose instead of docker compose.

Start n8n in one command

Create a volume for n8n's data, then start the container:

docker volume create n8n_data

docker run -it --rm \
  --name n8n \
  -p 5678:5678 \
  -e GENERIC_TIMEZONE="Europe/Berlin" \
  -e TZ="Europe/Berlin" \
  -e N8N_ENFORCE_SETTINGS_FILE_PERMISSIONS=true \
  -v n8n_data:/home/node/.n8n \
  docker.n8n.io/n8nio/n8n

Open http://localhost:5678 and create your owner account.

What each part does:

-p 5678:5678 maps the container's port to your machine. Change the left number if 5678 is taken: -p 8080:5678 serves n8n on http://localhost:8080.
GENERIC_TIMEZONE sets the timezone for schedule-based nodes. Get this wrong and your Schedule Trigger fires at the wrong hour. TZ sets the timezone for the operating system inside the container, which affects log timestamps. Set both, to the same value.
N8N_ENFORCE_SETTINGS_FILE_PERMISSIONS=true locks down the config file that holds your encryption key.
-v n8n_data:/home/node/.n8n is the important one. See the next section.

Two flags deserve a warning. -it attaches the container to your terminal, so closing that terminal stops n8n. --rm deletes the container when it stops. That combination is right for trying n8n out and wrong for anything you care about. For a container that keeps running, drop both and add -d:

docker run -d --name n8n --restart unless-stopped \
  -p 5678:5678 \
  -e GENERIC_TIMEZONE="Europe/Berlin" \
  -e TZ="Europe/Berlin" \
  -v n8n_data:/home/node/.n8n \
  docker.n8n.io/n8nio/n8n

--restart unless-stopped brings n8n back after a reboot or a crash.

On n8n 1.x, add -e N8N_RUNNERS_ENABLED=true. Task runners are how n8n executes code nodes, and on the 1.x line you have to opt in. From version 2.0 the variable is deprecated and you no longer need to set it. If you're on 2.0 or later and copied an older tutorial, you can drop it.

Where n8n stores your data

n8n keeps everything in /home/node/.n8n inside the container. That directory holds:

the SQLite database with your workflows, credentials, and execution history
the encryption key that your saved credentials are encrypted against
instance settings

Containers are disposable. Anything written inside one that isn't mapped to a volume disappears when the container is removed — and docker run --rm, docker rm, and most update procedures all remove containers. This is the single most common way people lose an n8n instance.

The -v n8n_data:/home/node/.n8n flag maps a Docker-managed named volume to that directory, so the data lives outside the container's lifecycle. Confirm it exists:

docker volume inspect n8n_data

The encryption key detail is worth dwelling on. Your credentials are encrypted with a key stored in that directory. Lose the volume and you don't just lose workflows — every saved credential becomes undecryptable, even if you have a database backup. Restoring means re-entering every API key by hand.

You can use a bind mount instead, pointing at a folder you can see:

-v ~/n8n-data:/home/node/.n8n

That makes backups as easy as copying a folder, but it introduces a permissions problem on Linux — see common errors below. Named volumes are the lower-friction default; bind mounts are better when you want direct file access.

docker run vs. Docker Compose

A long docker run command is fine once. It stops being fine the moment you need to remember it.

	`docker run`	Docker Compose
Trying n8n for ten minutes	Good	Overkill
Keeping an instance around	Painful — you must retype every flag	Good
Adding Postgres or Redis	Manual networking	Handles it
Updating	Stop, remove, retype the command	`pull` then `up -d`
Config lives in	Your shell history	A file you can version-control

Anything you intend to keep belongs in Compose. The configuration becomes a file you can read, diff, and back up, instead of a command you half-remember.

A Compose file for everyday local use

Create a folder, add a docker-compose.yml, and start it. This setup uses SQLite, which is the right choice for local development and light use:

services:
  n8n:
    image: docker.n8n.io/n8nio/n8n
    container_name: n8n
    restart: unless-stopped
    ports:
      - "5678:5678"
    environment:
      - GENERIC_TIMEZONE=Europe/Berlin
      - TZ=Europe/Berlin
      - N8N_ENFORCE_SETTINGS_FILE_PERMISSIONS=true
    volumes:
      - n8n_data:/home/node/.n8n

volumes:
  n8n_data:

Start it, and watch the logs:

docker compose up -d
docker compose logs -f

Press Ctrl+C to stop following the logs — the container keeps running. To stop n8n itself:

docker compose down

down removes the container but not the named volume, so your workflows survive. Adding -v to that command deletes the volume too, which is the destructive version. Don't type docker compose down -v on an instance you care about.

For a production setup with Postgres, HTTPS, and a reverse proxy, use the Compose file in the self-hosting guide instead — SQLite is fine locally but not what you want under real load.

The environment variables that matter

There are well over a hundred. These are the ones that change outcomes:

Variable	Why you'd set it
`GENERIC_TIMEZONE`	Timezone for Schedule Trigger and other time-based nodes. Wrong value = jobs at the wrong hour.
`TZ`	Operating-system timezone in the container. Affects log timestamps. Match it to `GENERIC_TIMEZONE`.
`N8N_ENCRYPTION_KEY`	Sets the credential encryption key explicitly instead of letting n8n generate one. Useful when you need reproducible deployments.
`N8N_SECURE_COOKIE`	Defaults to `true`, which means the session cookie is only sent over HTTPS. Accessing n8n over plain `http://` on anything other than localhost will fail to log in until you set this to `false`.
`N8N_ENFORCE_SETTINGS_FILE_PERMISSIONS`	Restricts permissions on the settings file holding your encryption key.
`N8N_PORT`	Changes the port inside the container. Usually unnecessary — remap with `-p` instead.
`N8N_RUNNERS_ENABLED`	Required as `true` on 1.x to enable task runners. Deprecated from 2.0 onward.

To use Postgres instead of SQLite, add:

DB_TYPE=postgresdb
DB_POSTGRESDB_HOST=postgres
DB_POSTGRESDB_PORT=5432
DB_POSTGRESDB_DATABASE=n8n
DB_POSTGRESDB_USER=n8n
DB_POSTGRESDB_PASSWORD=your-password

Even on Postgres, keep the /home/node/.n8n volume mounted. The database moves to Postgres, but the encryption key and instance settings still live in that directory.

Updating n8n, and rolling back

The image tag you use decides how much control you have. docker.n8n.io/n8nio/n8n with no tag means latest, so every pull can move you forward by an unknown amount. For anything you depend on, pin a specific version:

image: docker.n8n.io/n8nio/n8n:1.80.0

Back up before updating. With a named volume, the quickest snapshot is a tarball:

docker run --rm -v n8n_data:/data -v "$PWD":/backup alpine \
  tar czf /backup/n8n-backup.tar.gz -C /data .

Then update:

docker compose pull
docker compose down
docker compose up -d

Rolling back is why pinning matters: change the tag in docker-compose.yml back to the previous version and run docker compose up -d again. On latest, you have no easy way to name the version that was working.

Check what you're actually running:

docker compose logs n8n | head -20

Docker Desktop on Windows and macOS

The commands are identical, with three differences worth knowing.

Localhost works as expected. http://localhost:5678 reaches the container.

Bind mounts are slower. File operations across the Windows or macOS boundary carry overhead. Named volumes are meaningfully faster on these platforms — another reason to prefer them.

On Windows, keep files inside WSL2. If you use bind mounts, put the project folder in the WSL2 filesystem (\\wsl$\...) rather than under C:\Users\.... Crossing the filesystem boundary is slow and causes intermittent permission oddities.

Common Docker errors and fixes

All my workflows disappeared after a restart.
The container ran without a volume mapped to /home/node/.n8n. Unless you had a backup, that data is gone — containers don't keep filesystem changes after removal. Add -v n8n_data:/home/node/.n8n and rebuild. Verify with docker volume inspect n8n_data before you invest hours in building workflows.

EACCES: permission denied writing to /home/node/.n8n.
This hits bind mounts on Linux. The n8n container runs as the node user (UID 1000), and your host folder is owned by someone else. Fix ownership on the host:

sudo chown -R 1000:1000 ~/n8n-data

Named volumes don't have this problem, which is the main argument for them.

port is already allocated on 5678.
Something else holds the port — often a previous n8n container. Find it:

docker ps -a | grep 5678

Remove the old container, or remap: -p 8080:5678.

I can't log in — the page reloads back to the sign-in screen.
You're reaching n8n over plain http:// on a LAN IP or hostname. N8N_SECURE_COOKIE defaults to true, so the session cookie is only sent over HTTPS and never comes back. For local network use, set N8N_SECURE_COOKIE=false. Don't do that on a public server — set up HTTPS properly instead.

The container exits immediately.
Read the logs, which almost always name the cause:

docker logs n8n

Malformed environment variables and unreachable database hosts are the usual culprits.

Webhooks show a localhost URL that external services can't reach.
Expected: n8n advertises the address it thinks it has. For webhooks reachable from the internet you need a public URL and the WEBHOOK_URL variable, which is part of putting n8n on a real domain.

Frequently asked questions

Is the Docker version of n8n free?
Yes. The image is the Community Edition, which is free to self-host with unlimited workflow executions. Some features — SSO, projects, Git version control — are licensed separately, and the licence limits what you can do commercially. Is n8n free? covers both lists.

Do I need Docker Compose, or is docker run enough?
docker run is enough to try it. Use Compose for anything you keep — it turns a command you have to remember into a file you can back up.

Can I run n8n in Docker on a Raspberry Pi?
Yes, on 64-bit ARM hardware with enough RAM. A Pi 4 with 2 GB handles light workloads.

How do I move an instance to another machine?
Copy the /home/node/.n8n volume contents, including the encryption key. Move the database without the key and your credentials will be unreadable.

Where does n8n store workflows in Docker?
In the SQLite database inside /home/node/.n8n, unless you configured Postgres — in which case workflows live in Postgres, while the encryption key and settings remain in that directory.

Official references worth bookmarking: n8n's Docker installation docs and Docker's own guide to volumes.

Ready to build? The docker-compose.yml files above are complete — copy them straight out of this page. For workflows to run on top of it, our templates page has eight importable starters, including an error handler and a heartbeat monitor. Taking this to a real server with a domain and HTTPS? That's the complete self-hosting walkthrough.

n8n Telegram Bot: Build One That Sends and Receives Messages (2026)

Ali Ilyas — Sat, 15 Aug 2026 11:08:28 +0000

Originally published at noderecipe.com.

Building a Telegram bot in n8n takes about five minutes if all you want is outbound messages — notifications, alerts, a daily digest. Making the bot listen and respond is a different job, and it's where most first attempts stall.

The reason is a Telegram rule that has nothing to do with n8n: a bot can have exactly one webhook. n8n uses one URL when you're testing a workflow and a different one once it's active, so the two modes silently overwrite each other. Your bot works in the editor, then stops when you activate it — or the reverse — and nothing in the error explains why.

This guide covers the fast outbound path first, then the trigger, then that constraint and how to work around it properly.

What you'll need

A Telegram account.
A running n8n instance. Outbound messages work anywhere, including a local instance on localhost. Receiving messages requires a public HTTPS URL — Telegram will not deliver updates to localhost or to plain http://. If you're running locally, n8n in Docker is the quickest start; for the trigger you'll need a real domain with HTTPS.

That split is worth internalizing before you begin. Half of this guide works on a laptop; the other half doesn't, and no amount of configuration changes that.

Create the bot with BotFather

BotFather is Telegram's official bot for creating bots. Open a chat with @BotFather and send:

/newbot

It asks for two things:

Name — the display name people see. Changeable later.

Username — the permanent identifier. The rules: 5 to 32 characters, not case sensitive, Latin characters, numbers and underscores only, and it must end in bot (tetris_bot, my_alerts_bot). This one cannot be changed afterward, so pick something you won't regret.

BotFather then gives you an access token that looks roughly like 8123456789:AAF.... Treat it like a password — anyone holding it controls your bot completely.

Add the credential in n8n

In n8n, create a new Telegram API credential and paste the token into the Access Token field. Save.

That's the entire credential setup. No OAuth flow, no consent screen, no Google Cloud project — a pleasant contrast to connecting Google Sheets, where credentials are most of the work.

Send your first message

Add a Telegram node, set Resource to Message and Operation to Send Message. Two fields matter:

Chat ID — where the message goes. For a public channel you can use @channelusername. For anything else you need the numeric ID, which is the next section.

Text — up to 4096 characters after entity parsing. Longer messages are rejected rather than truncated, so if you're piping in generated or scraped content, split it before it reaches this node.

Before you run it: a bot cannot message you first. Telegram requires the user to initiate contact. Open your bot's chat and send it /start, or the send will fail no matter how correct your configuration is. For a group or channel, add the bot as a member — and as an administrator if it needs to post to a channel.

One setting you'll want immediately. By default n8n appends its own attribution line to outgoing messages. To remove it, open Additional Fields → Add Field and turn off Append n8n Attribution. Most people don't notice this until a client asks why the bot is advertising software.

Finding your chat ID

The most common blocker on this integration, and there are three ways through it.

Use the Telegram Trigger. Add a Telegram Trigger node, execute it, and message your bot. The output contains the chat object, and chat.id is what you want. This is the most reliable method because it gives you the exact value Telegram will use. It needs a publicly reachable instance, though — see the trigger section below.

Read it from Telegram Web. Open the group in a browser. The chat ID is the run of digits after the letter g in the URL. Prefix it with - when you enter it in n8n — group IDs are negative, and omitting the minus sign is a frequent, confusing failure.

Invite @RawDataBot. Add Telegram's @RawDataBot to the group. It immediately posts a JSON dump; the id inside the chat object is your chat ID. Remove the bot afterward.

Note that @channelusername only works for public channels. Private groups have no username, so there the numeric ID is the only option.

Formatting messages without breaking them

Under Additional Fields, Parse Mode offers three choices: HTML (the default), Markdown (Legacy), and MarkdownV2.

Use HTML unless you have a specific reason not to. MarkdownV2 looks like the modern option and is the biggest source of avoidable errors on this node, because it requires escaping a long list of reserved characters — including the period. A message ending in a normal sentence full stop can fail to parse. The resulting Bad Request: can't parse entities error points at Telegram's parser, not at your text, so the cause is rarely obvious.

HTML needs only <b>, <i>, <code>, <pre>, and <a href="">, and it doesn't blow up on punctuation:

<b>Deploy finished</b>
Build <code>a1b2c3d</code> is live.
<a href="https://example.com/logs">View logs</a>

Two other fields worth knowing:

Disable Notification — delivers silently. Right for high-frequency or low-priority alerts.
Disable WebPage Preview — suppresses the link preview card, which otherwise dominates short messages containing a URL.

Receiving messages with the Telegram Trigger

The Telegram Trigger is a separate node that starts a workflow when something happens in Telegram. It offers a long list of update types — Message, Edited Message, Channel Post, Callback Query, Inline Query, Poll Answer, Chat Member, Chat Join Request, and more, plus * for all updates, which is the default.

Set this deliberately, and check it covers what you're actually sending. Leaving it on * means your workflow fires on events you never intended to handle, including your own bot's status changes. Narrowing it too far causes the opposite and more confusing problem: a trigger listening only for text messages silently ignores photos and documents. Nothing errors, because from the trigger's side nothing relevant happened. Worse, running the node manually often bypasses these filters, so it passes your test and then ignores real traffic.

In groups, privacy mode limits what your bot can see. Telegram enables it by default, which means a bot added to a group only receives messages that are commands or that mention it — not ordinary conversation. If your group bot reacts only sometimes, that's why. Turn it off through BotFather with /setprivacy, then remove and re-add the bot to the group for the change to apply.

Three options are worth setting:

Download Images/Files — fetches attachments and hands them to the next node as binary data rather than giving you a file reference you'd have to resolve yourself. Image Size controls which resolution you get.

Restrict to Chat IDs and Restrict to User IDs — comma-separated allowlists. For a bot that isn't meant to be public, set at least one of these. A Telegram bot's username is discoverable, and without a restriction anyone who finds it can trigger your workflow.

Unlike the Google Sheets Trigger, which polls on a schedule, this one is a genuine webhook — Telegram pushes updates to n8n the moment they happen. That's why it's instant, and also why it has the constraint in the next section.

The one-webhook-per-bot problem

This is the part that costs people an evening.

n8n gives a workflow two webhook URLs: a test URL used while you're clicking Execute workflow in the editor, and a production URL used when the workflow is active. Every other trigger handles this fine.

Telegram doesn't, because Telegram only allows a single registered webhook per bot. Whichever mode registered last wins. So:

You test in the editor. n8n registers the test URL. It works.
You activate the workflow. n8n registers the production URL, overwriting the test one.
You go back to the editor to debug. The test registration overwrites production — and your live bot goes quiet.

Nothing errors. The bot simply stops responding in the mode you're not currently using, which is exactly the symptom that sends people hunting through their workflow logic for a bug that isn't there.

There are two clean fixes:

Create a second bot for development. Run /newbot again, make a separate n8n credential, and point your development copy of the workflow at it. This is the right answer for anything real — you get an isolated test environment and your live bot is never interrupted.

Or deactivate the workflow while testing, then reactivate it. Free, but it means your bot is down whenever you're working on it, and it's easy to forget the reactivation step.

If you run more than one workflow off the same bot, the same rule applies: they compete for the single webhook slot. Route all updates into one trigger and branch with a Switch node, rather than running several triggers on one token.

Skip the build. The Telegram Command Bot workflow is ready to import — grab the JSON and paste it onto the canvas, or browse all the templates.

This isn't unique to Telegram — Slack has the same one-request-URL-per-app rule, with the same symptom and the same fix. It's worth recognizing the pattern, because it shows up wherever a platform tracks a single callback address per integration.

Buttons, replies, and inline keyboards

Reply Markup on the Send Message operation turns a message into something interactive. Four types:

Inline Keyboard — buttons attached under the message itself. The usual choice.
Reply Keyboard — replaces the user's keyboard with preset options.
Reply Keyboard Remove — dismisses that keyboard.
Force Reply — makes the client open a reply box automatically.

Inline keyboard buttons emit a Callback Query rather than a message, so your Telegram Trigger must include that update type or the taps go nowhere.

One requirement people miss: after handling a callback you should run the Callback → Answer Query operation. Until you do, Telegram shows a loading spinner on the button in the user's client. The action succeeds, but the interface looks broken.

To reply in the same thread rather than as a new message, set Reply To Message ID from the incoming message. In forum supergroups, Message Thread ID keeps replies inside the right topic.

Sending photos and files

Message operations cover Send Photo, Send Document, Send Video, Send Audio, Send Animation, Send Sticker, Send Media Group, and Send Location.

Each takes either binary data from a previous node — enable Binary File — or a reference. For references you have two options: an HTTP URL that Telegram fetches itself, or a file_id from a file Telegram already has. Prefer file_id when resending something the bot has seen before; it's instant and skips the upload entirely.

Going the other way, File → Get File retrieves a file a user sent to your bot.

Two limits worth planning around: Send Animation is documented for GIFs and soundless H.264/MPEG-4 up to 50 MB, and Telegram's Bot API is far more restrictive about uploads than the regular Telegram client. If you're moving large files, check the current Bot API limits rather than assuming client behavior applies.

Common errors and fixes

Bad request: bad webhook: An HTTPS URL must be provided for webhook
Telegram won't send updates to anything but a public HTTPS address. This appears when n8n sits behind a reverse proxy that hasn't been told its own public URL. Set the WEBHOOK_URL environment variable to your public HTTPS address and terminate TLS in the proxy. That variable is covered in the Docker setup guide, and the full proxy configuration in the self-hosting walkthrough.

Error: Forbidden: bot is not a participant of the channel
The bot isn't in the channel. Add it through the channel's settings by searching its username — and make it an administrator, which channels require for posting.

The bot never responds, and there's no error at all.
Almost always the webhook collision above. Check whether the workflow is active, and whether you last executed it from the editor.

The execution hangs, waiting for a trigger event.
On self-hosted instances this is typically a reverse proxy without websocket support. Enable websocket proxying in Nginx, Caddy, Apache, or Traefik.

Bad Request: can't parse entities
Your Parse Mode doesn't match your text. Switch to HTML, or escape every reserved character MarkdownV2 requires.

Messages stop sending during a bulk run.
Telegram's API caps sending at roughly 30 messages per second. Batch with a Loop Over Items node and add a delay between batches rather than firing a node once per recipient.

Messages arrive with an n8n advert appended.
Turn off Append n8n Attribution under Additional Fields.

Chat ID is rejected as invalid.
For groups, you're probably missing the leading -. Group IDs are negative numbers.

Frequently asked questions

Can my bot message someone who hasn't contacted it first?
No. Telegram requires the user to start the conversation, which is a deliberate anti-spam rule. For groups and channels, the bot has to be a member.

Do I need a server to build a Telegram bot in n8n?
Only for receiving. Sending works from a local instance. The trigger needs a publicly reachable HTTPS URL because Telegram pushes updates to you.

Can two workflows use the same bot?
Not reliably — they compete for the bot's single webhook registration. Use one trigger and branch internally, or create a second bot.

Is a Telegram bot free?
Yes. Telegram's Bot API has no cost. Your only expense is wherever n8n runs.

How do I log messages to a spreadsheet?
Chain a Google Sheets node onto the Telegram Trigger and append a row per message — the pattern is in the Google Sheets integration guide.

Can the bot respond to slash commands like /status?
Yes. Commands arrive as ordinary message text, so branch on the text with a Switch node. Register the command list with BotFather via /setcommands so it autocompletes for users.

Can the bot handle voice notes?
Yes, and it's one of the better uses for a Telegram bot. Download the file with the Telegram node, then transcribe it — the OpenAI integration guide has that build step by step.

Official references worth bookmarking: n8n's Telegram node documentation and Telegram's own Bot API reference.

Want it prebuilt? Importable Telegram workflows — a command-driven bot with the @botname suffix already handled, and an error alerter — are on our templates page. Need the public HTTPS URL the trigger depends on? That's the self-hosting guide, and n8n in Docker if you're starting from scratch.

n8n Google Sheets Integration: Connect, Read, and Write Rows (2026)

Ali Ilyas — Sun, 09 Aug 2026 10:48:16 +0000

Originally published at noderecipe.com.

Google Sheets is the integration most people wire up first in n8n, and the node itself is easy. Almost all of the difficulty is in the ten minutes before it: getting Google to hand n8n a working credential. That step has more places to go wrong than the entire rest of the workflow, and most guides skip past it in two sentences.

This one doesn't. We'll set up the credential properly, then build the three things you'll actually use — appending rows, reading rows with a filter, and updating a row that already exists — and finish with the gotchas that quietly cost people an afternoon.

What you'll need

A running n8n instance. Either n8n Cloud or a self-hosted one — the difference matters a lot for credentials, and we'll cover it below. If you don't have one yet, the quickest local option is n8n in Docker.
A Google account.
A spreadsheet with a header row. n8n reads your column names from the first row, so a sheet whose first row is data rather than headers will behave strangely from the start.

Everything below was checked against n8n 2.x. Where a detail changed between major versions, it's called out.

Connecting Google Sheets to n8n

n8n supports two ways to authenticate with Google: OAuth2 and a Service Account. Both work with Google Sheets. n8n recommends OAuth2 as the default, and for most people that's the right call.

The important fork is where your n8n runs:

On n8n Cloud, Google Sheets is one of the nodes covered by managed OAuth2. You pick the credential, click through Google's consent screen, and you're done. No Google Cloud Console, no client ID. If you're on Cloud, skip to the operations.

Self-hosted, managed OAuth2 isn't available. You have to create your own OAuth client in Google Cloud Console, or use a service account. This is the step people get stuck on, so it gets its own section.

That gap is worth understanding rather than resenting. The managed credential works because n8n owns a verified OAuth app registered against its own domain. A self-hosted instance is a different application at a different address as far as Google is concerned, so Google needs you to register it.

Setting up custom OAuth2, step by step

Budget ten minutes the first time. Once the Google Cloud project exists, adding more Google services to it takes about one minute each.

1. Create a Google Cloud project

In the Google Cloud Console, open the project dropdown in the top bar and choose New project. Name it something you'll recognize — n8n-automation is fine. Make sure it's selected in the top bar before continuing.

2. Enable both APIs

Go to APIs & Services → Library. Enable:

Google Sheets API
Google Drive API

Enabling only the Sheets API is the single most common mistake here. n8n uses the Drive API to list your spreadsheets in the Document dropdown, so without it the node authenticates fine and then shows you an empty list — which looks like a permissions bug and isn't one. Google Docs and Slides have the same requirement.

3. Configure the OAuth consent screen

Go to APIs & Services → OAuth consent screen and select Get started.

Enter an app name and user support email.
Choose your audience: Internal limits access to accounts in your Google Workspace organization. External allows any Google account, and is what you'll pick if you're on a personal Gmail account.
Add contact email addresses and accept the User Data Policy.
Under Branding → Authorized domains, add n8n.cloud if you're on Cloud, or your own domain if you're self-hosting.

Read this part before you continue. If you choose External, your app starts in Testing mode. Two consequences follow:

Only Google accounts you explicitly add as test users can complete the OAuth flow. Add yours under Audience.
Consent and tokens expire after seven days. Your workflow runs perfectly all week and then fails on day eight with an auth error, for no reason you changed.

That second one is the highest-frustration item on this page, because the failure arrives long after the setup that caused it. If this is a workflow you intend to keep, publish the app rather than leaving it in Testing.

4. Create the OAuth client

Go to APIs & Services → Credentials → + Create credentials → OAuth client ID, and choose Web application as the application type.

Now switch to n8n. Create a new Google Sheets OAuth2 API credential, and copy the OAuth Redirect URL it displays. It follows this shape:

https://your-n8n-domain.com/rest/oauth2-credential/callback

Paste that into Authorized redirect URIs in Google Cloud Console and select Create. Google shows you the Client ID and Client Secret in a modal — copy both now, because the secret isn't fully visible again later.

If you're developing locally, this works without SSL or port forwarding:

http://localhost:5678/rest/oauth2-credential/callback

Copy the URL exactly as n8n gives it to you, including the protocol and port number. A redirect_uri_mismatch error almost always means one of those three differs — http against https, a missing :5678, or a trailing slash. Google matches this string literally.

One consequence for self-hosters: a public n8n instance needs a stable HTTPS address before this credential is worth creating, because the redirect URI is registered against a fixed URL. If your instance is still on a bare IP or a tunnel URL that changes, sort out a real domain and certificate first — otherwise you'll be re-registering the redirect URI every time the address moves.

5. Finish in n8n

Paste the Client ID and Client Secret into the n8n credential, click Sign in with Google, complete the consent flow, and save. If your app is External and in Testing, you'll see an "unverified app" warning — expected, and you can proceed through it for an app you created yourself.

The scopes n8n requests for Sheets are:

https://www.googleapis.com/auth/spreadsheets
https://www.googleapis.com/auth/drive.file

drive.file is deliberately narrow: it grants access only to files opened or created through the app, not your whole Drive.

When to use a service account instead

A service account is a robot Google account with its own email address. Instead of a consent flow, you share the spreadsheet with that address the same way you'd share it with a colleague.

Use one when:

The workflow belongs to a team or a server rather than to you personally. Service account access doesn't disappear when someone leaves.
You want to avoid the seven-day token expiry entirely.
The instance runs unattended and nobody will be around to re-authorize it.

Stay with OAuth2 when the sheets are your own and you want the fastest setup. One caveat worth knowing: Google supports service accounts with Gmail only through domain-wide delegation, which Google discourages and which behaves inconsistently — so n8n recommends OAuth2 for Gmail specifically. For Sheets, both are fully supported.

The thing people forget with service accounts: share the sheet with the service account's email address. Nothing works until you do, and the resulting permission error doesn't say so.

The operations, and which one you want

The Google Sheets node has two resources. Document operates on the spreadsheet file (Create, Delete). Sheet Within Document operates on a tab inside it, which is where nearly all real work happens:

Operation	Use it when
Append Row	Adding new records. Never touches existing rows.
Append or Update Row	You don't know whether the record exists yet — the upsert.
Update Row	The row definitely exists and you're changing it.
Get Row(s)	Reading data out, optionally filtered.
Clear	Wiping a sheet's contents before a fresh load.
Delete Rows or Columns	Removing rows or columns by position.
Create / Delete	Adding or removing a tab.

If you're unsure between the first three: use Append Row for logs and event streams where every entry is new, and Append or Update Row for anything keyed on an identifier — a customer email, an order ID — where running the workflow twice shouldn't produce two rows.

Every operation shares the same two selectors. Document and Sheet can each be picked From list, By URL, or By ID (Sheet also offers By Name). Use From list while building, since it confirms your credential can actually see the file. Switch to By ID or an expression when the sheet is chosen dynamically at runtime.

Build 1: append incoming data to a sheet

The most common workflow in n8n: something happens, write a row about it.

Add a trigger. A Webhook node works for form submissions; a Schedule Trigger works for periodic jobs.
Add a Google Sheets node. Set Resource to Sheet Within Document and Operation to Append Row.
Select your Document and Sheet.
Set Mapping Column Mode.

That last setting is the one to understand. It has three options:

Map Automatically — n8n matches incoming field names to column headers. Clean and fast when your data's keys already match your headers exactly.
Map Each Column Manually — n8n lists your sheet's columns and you drag or type an expression into each. More clicks, far more predictable.
Nothing — pass the raw data through untouched, for cases where you're shaping it upstream.

Start with Map Each Column Manually while you're learning. Automatic mapping is silent when it fails: a field whose name doesn't match a header simply doesn't get written, and you get a row with blank cells rather than an error.

Three options are worth setting under Options:

Cell Format — Let Google Sheets format (the default) means Google interprets your values the way it would if you typed them, so 1/2 may become a date and a leading + may become a formula. Let n8n format writes values as-is. If you're writing product codes, phone numbers, or anything with leading zeros, choose Let n8n format.

Data Location on Sheet — sets which row holds your headers and which row your data starts on. Change these if your sheet has a title block above the table.

Handling extra fields in input — what happens when your data contains a key with no matching column: Insert in New Column(s), Ignore Them, or Error. For a workflow you want to trust, Error is the honest choice — it surfaces schema drift instead of hiding it.

Build 2: read rows and filter them

Set Operation to Get Row(s). With no filters, it returns every row as an n8n item.

Add a Filter to narrow it: pick a Column, give it a Value, and only matching rows come back. Under Options, When Filter Has Multiple Matches decides whether you get the first match or all of them — set it deliberately, because the default behavior surprises people building "look up this customer" workflows.

Also under Options, Output Formatting controls what you actually receive:

Values unformatted — the raw underlying value. A currency cell comes through as 1234.5, not $1,234.50.
Values formatted — the display string, as shown in the sheet.
Formulas — the formula text rather than its result.

Choose unformatted when the number feeds a calculation, and formatted when it feeds a message someone will read. Getting this backwards produces the classic bug where a total is off because $1,234.50 was parsed as a string.

Build 3: update a row instead of duplicating it

Append or Update Row is the operation that makes a workflow safe to re-run.

Set Mapping Column Mode to Map Each Column Manually, and a Column to Match On appears. That column is the identity key. n8n looks for a row whose value in that column matches your incoming data — if it finds one, it updates that row; if not, it appends a new one.

Pick something genuinely unique. Email addresses and order IDs work. Names don't.

Two limits to plan around:

You can only match on one column. There's no composite key. If your identity is genuinely two fields, build a combined key column in the sheet — email|date, say — and match on that.

The "Use Append" option is a performance trade. Enabling it uses Google's append endpoint, which means fewer API calls and better throughput on large runs. The documented cost: if your existing sheet data has gaps or breaks between rows and columns, n8n can place new data in the wrong location. Leave it off on a messy sheet; turn it on for a clean, densely-populated one where you're writing a lot.

Triggering a workflow when a row is added

The Google Sheets Trigger is a separate node from the one above, and it starts a workflow when the sheet changes. Three events are available:

Row added
Row updated
Row added or updated

This is a polling trigger, not a push. Google doesn't notify n8n; n8n checks the sheet on the interval you configure. Two things follow. Detection is not instant — it's bounded by your polling interval. And a row added and then deleted between two polls is never seen at all.

For anything needing true real-time behavior, have the upstream system call an n8n Webhook node directly rather than routing it through a spreadsheet. That needs a publicly reachable instance, which is the self-hosting setup. The Telegram Trigger is a good example of the push model for comparison — updates arrive the instant they happen, at the cost of requiring a public HTTPS address.

Two documented issues are worth knowing before they bite:

Dates arrive as numbers like 45678.5. That's Google's serial format — the whole number is days since December 30, 1899, and the decimal is the fraction of a 24-hour day. Fix it in the node: Add option → DateTime Render → Formatted String. This applies when Trigger On is set to Row Added. The resulting format follows your spreadsheet's locale, which you can change under File → Settings → Locale.

The execution appears stuck waiting for a trigger event. On self-hosted instances this is usually a reverse proxy without websocket support. Enable websocket proxying in Nginx, Caddy, Apache, or Traefik — whichever sits in front of n8n. The self-hosting guide covers a configuration that has this set correctly.

Gotchas that cost people hours

The Document dropdown is empty even though the credential connected.
The Google Drive API isn't enabled on your Google Cloud project. Sheets API alone authenticates but can't list files.

redirect_uri_mismatch when signing in.
The redirect URI in Google Cloud Console doesn't match n8n's byte for byte. Check protocol, port, and trailing slash.

It worked for a week, then stopped.
Your OAuth app is External and still in Testing mode, where consent and tokens expire after seven days. Publish the app, or move to a service account.

"Column names were updated after the node was set up."
You changed headers in the sheet after configuring the node. n8n cached the old ones. Re-select the Mapping Column Mode option to refresh the column list, then fix any parameters that referenced the old names.

An array field writes as [object Object] or errors.
Google Sheets cells hold single values, so an array has to be flattened into key/value pairs first. Use a Split Out node to turn each array element into its own item and its own row, or a Code node to join them into a string if one cell is what you want.

One row goes in, but you expected many.
n8n runs the node once per input item. If your data arrived as a single item containing an array of records, you get one row. Split it first — same Split Out node.

Leading zeros vanish and codes turn into dates.
Google is interpreting your values. Set Cell Format to Let n8n format.

A permission error with a service account.
You didn't share the spreadsheet with the service account's email address. Open the sheet, hit Share, paste that address, give it Editor.

Frequently asked questions

Do I need a paid Google Workspace account?
No. A free personal Google account works. Workspace only matters if you want the Internal audience option, which avoids the Testing-mode expiry.

Is there a limit on how much data I can write?
Google's Sheets API enforces per-minute quotas per project and per user, so very high-frequency writes will hit rate limits. Batch your writes rather than calling the node once per record, and be aware that a spreadsheet is a poor substitute for a database above a few tens of thousands of rows.

Can n8n read a sheet shared with me by someone else?
Yes, provided your Google account has access. With OAuth2 the drive.file scope covers files you open through the app. With a service account, the owner has to share the sheet with the service account address.

Why does my number come through as a string?
Output Formatting is set to Values formatted. Switch to Values unformatted for the raw value.

Can I use one credential for Sheets, Drive, and Gmail?
You can reuse one Google Cloud project for all of them, but n8n uses a separate credential type per service. Enable each API in the same project and create each credential against the same OAuth client.

Does this work the same on n8n Cloud and self-hosted?
The node is identical. Only the credential setup differs — Cloud gives you managed OAuth2, self-hosted requires the custom client above.

Official references worth bookmarking: n8n's Google Sheets node documentation and Google's Sheets API authorization scopes.

Want this as a working workflow? Importable workflows built on Sheets — validated webhook capture, a lookup-before-write guard, and a scheduled heartbeat monitor — are on our templates page. Running n8n yourself and still setting things up? Start with n8n in Docker, then put it on a real domain with HTTPS so your OAuth redirect URI stops moving.

n8n Workflow Not Triggering? Work Through It in This Order (2026)

Ali Ilyas — Fri, 07 Aug 2026 10:04:49 +0000

Originally published at noderecipe.com.

A workflow that won't trigger gives you almost nothing to work with. No error, no failed execution, no red node — just silence. So the instinct is to start rebuilding the trigger, which is usually the one thing that isn't broken.

Work through the checks below in order instead. They're arranged by how often they turn out to be the cause, and the first two account for the clear majority of cases.

One thing to know before you start, because it invalidates a lot of older advice: n8n renamed the "Active" toggle to a "Publish" button. If you're following a guide that tells you to flip a switch labelled Active and you can't find it, the guide predates the change. Same concept, different control.

Start here: is the workflow published?

The single most common cause, and the easiest to overlook once you've been staring at the same canvas for an hour.

Manual executions and production executions are different things. Clicking Execute workflow runs the workflow ad-hoc from the canvas. It does not make the trigger live. A workflow only responds to real events once you attach a non-manual trigger and publish it.

So: open the workflow and confirm it's published. Then confirm you published the version you're looking at — editing a published workflow doesn't push the changes live on its own. Save, then publish again.

This also catches a subtler variant. If your workflow has a Manual Trigger node still attached from when you were building it, and no other trigger, there is nothing for n8n to activate. Manual triggers never fire on their own.

After a bulk import or migration, check publish state explicitly. Imported workflows can land effectively inactive while still looking normal in the workflow list. If a batch of workflows all went quiet at once and they were recently imported or migrated, check them one at a time rather than trusting the list view. Importing templates covers the other things that arrive half-configured — placeholders, node version mismatches, and instructions written against an older n8n.

The Publish control is greyed out or missing

A distinct problem worth separating out: you can't publish at all, so nothing about triggers applies yet.

You can't click Publish. Two usual causes. First, unsaved changes — n8n won't publish a workflow that isn't saved, and every node edit puts it back into an unsaved state, so a tweak after your last save is enough. Hit save, and the control wakes up. Second, a validation problem in the trigger node — an empty required field like a webhook path, or an unset HTTP method, blocks publishing even when the node looks fine at a glance. Open the trigger and look for a warning marker.

Hover the control before guessing. n8n generally shows a tooltip naming the reason.

There's no Publish control at all. An empty canvas has nothing to publish. You need at least a trigger node and something connected to it. This confuses people following older video tutorials, where an Active toggle was visible from the start on a blank workflow — that toggle no longer exists.

Are you using the test URL or the production URL?

Every webhook-style trigger in n8n has two URLs, and they behave completely differently.

The test URL only listens after you select Listen for test event, and it stays open for 120 seconds. Its advantage is that incoming data appears in the editor, which makes it the right tool for debugging. Its disadvantage is that it goes dead two minutes later, which produces the classic "it worked when I tested it and stopped an hour later."

The production URL is live whenever the workflow is published, and stays live until you unpublish it. Data flowing through it is not shown in the editor — that's expected, not a fault. Check the executions list instead.

If you registered the test URL with an external service, that service is now calling a URL that stopped listening. Swap it for the production URL and republish.

Read the executions list before anything else

This is the step that saves the most time, and it's the one people skip.

Open the workflow's executions. What you see splits the problem in half:

No execution at all — the trigger never fired. The cause is in this article: publish state, wrong URL, timezone, or a platform-side registration problem.

An execution that failed — the trigger fired correctly and something downstream broke. That's a different problem entirely, and the execution will name the failing node. Stop looking at the trigger.

An execution that succeeded but did nothing useful — the trigger fired with empty or unexpected data. Jump to It triggers, but nothing happens.

Getting this wrong is how people spend an evening rebuilding a trigger that was working the whole time.

It works when I run it manually

This deserves its own answer, because it's the most misleading symptom in the whole list. The workflow runs perfectly from the canvas, so the logic is obviously fine — and people conclude the trigger is broken when it usually isn't.

Manual execution and live execution don't apply the same filters. Running a node by hand often bypasses the trigger's event filtering just to test the connection. Once published, the trigger enforces its filter strictly. So a Telegram Trigger set to receive only text messages will pass a manual test and then ignore every photo and document you send it — nothing errors, because from the trigger's point of view nothing relevant happened.

The fix is to check what your trigger is actually subscribed to, not whether it responds when poked. In practice that means the allowed update or event types on app triggers, and the HTTP method on webhooks.

Credentials also behave differently. A manual run happens while you're sitting there with a fresh session. A production run at 3am uses a stored token that may have expired since. If manual works and scheduled doesn't, suspect the token before the trigger.

Webhook triggers

The URL returns 404. Almost always the workflow isn't published, or you're calling the test URL outside its 120-second window.

Two workflows share a path. n8n allows only one webhook per path and method combination. A second published workflow using the same pair won't register, and publishing fails. Note it's the pair that has to be unique — a GET and a POST on the same path coexist happily, which is why one method can work while the other refuses. Unpublish the conflicting workflow, or change the path.

If both workflows are yours, webhooks are the wrong tool for the job. Use the When Executed by Another Workflow trigger with an Execute Sub-workflow node instead: no URLs, no path conflicts, and data passes directly.

The sender uses a method your node doesn't accept. A Webhook node listens for a single HTTP method by default. If the service sends POST and your node expects GET, nothing arrives and nothing errors. Either match the method or enable Allow Multiple HTTP Methods.

Your IP allowlist blocks legitimate traffic. Behind a reverse proxy, n8n sees the proxy's IP rather than the caller's. Set N8N_PROXY_HOPS to the number of proxies in front of n8n so the real client IP is resolved.

The webhook URL points at localhost. External services can't reach your machine. n8n advertises whatever address it believes it has, so behind a proxy you need WEBHOOK_URL set to your public HTTPS address — the variable is covered in the Docker setup guide, and the proxy configuration in the self-hosting walkthrough.

It responds, but the caller times out. Long-running workflows can exceed the caller's patience. Split it: one webhook that responds immediately and starts the work, and a second the caller polls for status.

Schedule triggers

The timezone is wrong. The most common cause by a wide margin, and it's easy to misread as "didn't fire" when it actually fired at 3am. Set GENERIC_TIMEZONE on self-hosted instances, or the timezone in your n8n Cloud settings. You can also override it per workflow: three-dot menu → Settings → Timezone.

Your cron expression is invalid. When Trigger Interval is Custom (Cron), a malformed expression means n8n never schedules anything. Validate it — dropping the seconds column — at crontab.guru.

The schedule restarts from when you publish. This one surprises people: after changing an interval, the schedule recalculates from the moment of publication, not from the original start time. If you republish an hourly workflow at 2:40, it runs at 3:40, not 3:00. To apply a changed interval at all, unpublish and publish a new version.

Variables aren't picking up new values. Variables in a Schedule Trigger are evaluated at publish time. Changing a variable's value does nothing until you publish a new version.

The instance was down when the run was due. By default n8n schedules in memory, and a run whose time passes during downtime is skipped rather than caught up. A nightly job on a server that reboots at 3am simply doesn't happen that night, with no record that it should have.

If that matters, self-hosted instances can opt into the durable scheduler, which records runs in a database-backed queue in advance so a missed run fires when the instance recovers. It's off by default and needs both N8N_SCHEDULER_ENABLED=true and N8N_USE_WORKFLOW_PUBLICATION_SERVICE=true. Worth enabling for anything where a skipped run has consequences.

App triggers: Telegram, Slack, Google Sheets

Service-specific triggers add their own failure modes on top of everything above.

Telegram and Slack: the single-callback rule. Telegram permits one webhook per bot; Slack permits one request URL per app. n8n uses a test URL in the editor and a production URL when published, so the two overwrite each other. Symptom: the workflow works in one mode and goes silent in the other, with no error. Fix: a separate bot or app for development. Full detail in the Telegram guide and the Slack guide.

The trigger is subscribed to the wrong event. The most common version of this: a Telegram Trigger left on its default update types receives text messages but not photos or documents. You send a file, nothing happens, and no error appears — the trigger correctly ignored an event it wasn't listening for. Add the update types you actually need.

A Telegram bot in a group can't see most messages. Telegram's bot privacy mode is on by default, which limits a bot in a group to messages that are commands or that mention it directly. If your group bot only reacts sometimes, this is why. Change it through BotFather with /setprivacy, then remove and re-add the bot for it to take effect.

Polling triggers aren't instant. The Google Sheets Trigger checks on an interval rather than being pushed to. Detection is bounded by that interval, and a change made and reverted between two polls is never seen. That's the design, not a bug — if you need immediacy you need a push-based trigger.

Credentials expired. A trigger that stops after working for days is usually auth, not logic. Two specific traps worth checking: a Google OAuth app left in Testing mode expires consent after seven days, and a Slack app with token rotation enabled expires tokens every 12 hours. Both are covered in their respective guides.

The nasty part is how an expired credential presents on a polling trigger. It often doesn't error — the poll returns an empty result instead. So the workflow keeps "running fine" forever while doing nothing, and no failure alert ever fires.

The bot lost channel access. If a bot was removed from a channel, or a Google service account lost access to a sheet, events stop arriving with no error on the n8n side.

Self-hosted-only causes

The host went to sleep. Free and low-tier hosting plans suspend idle containers, and a suspended instance runs no schedules. This is a common cause of an every-minute trigger that fires erratically or not at all. If your instance sleeps, either move to an always-on plan or accept that time-based triggers won't be reliable.

n8n isn't running. Obvious, and worth ruling out in ten seconds:

docker ps
docker logs n8n --tail 50

A container that exited or is restart-looping explains everything above it. See common Docker errors if it won't stay up.

Your public URL changed. Tunnel URLs from ngrok and similar tools rotate. Every webhook you registered with an external service now points somewhere that no longer exists. This is the strongest practical argument for a stable domain with HTTPS.

The reverse proxy is dropping requests. Check the proxy's access log, not just n8n's. If the request never reaches n8n, n8n can't tell you about it. Trigger nodes that appear to hang while listening usually mean websocket support isn't enabled in Nginx, Caddy, Apache, or Traefik.

HTTPS isn't actually terminating. Telegram and Slack both refuse to deliver to plain http://. A valid certificate isn't optional for those triggers.

It triggers, but nothing happens

The execution list shows successful runs, but nothing downstream changed.

Zero items reached the next node. A node that receives no items doesn't run, and this cascades silently through the rest of the workflow. Look at the item count on each connection — the first 0 is your answer. A Filter or IF node that matched nothing is the usual culprit.

A filter is stricter than you think. String comparisons are exact. "Active" doesn't match "active", and a trailing space breaks equality invisibly.

The trigger fired on the wrong event. A trigger set to all events fires on things you never meant to handle — including your own bot's activity. Narrow the event type.

You're editing one workflow and running another. Duplicated workflows with near-identical names are more common than they sound. Confirm the execution belongs to the workflow you're editing.

Make the next failure visible

Silent failure is the real problem here. A wrong trigger is only the symptom, and you found it by noticing something didn't happen — which means you found it late.

An Error Trigger is not enough, and this is the part people get wrong. An error workflow fires when an execution fails. Every failure mode in this article produces no execution at all, so there is nothing to fail and nothing to report. The alert you set up specifically to catch problems is structurally blind to the most common one.

Three principles make monitoring actually work:

Alert on absence of success, not presence of failure. Have each critical workflow write a timestamp somewhere cheap — a database row, a key-value store, a spreadsheet — and run a separate watcher that alerts when a timestamp goes stale: "this should run hourly, last success was three hours ago." That single check catches deactivated triggers, expired tokens, and the empty-poll case above, none of which ever raise an error.

Write that timestamp conditionally on real output. If you log it unconditionally at the end of the run, a green execution that produced nothing still marks itself healthy — and you've built a monitor that confirms your silent failure is fine. Assert on the actual result: rows returned, message sent, record created.

The watcher must not share fate with what it watches. This is the one that catches people out. A heartbeat running inside the same n8n instance dies with that instance and goes quiet at exactly the moment you needed it to shout. The same applies to any shared dependency — using the same credential, the same API provider, or the same database in both the workflow and its error handler means one outage blinds both at once. Put the watcher somewhere else: a cron job on a different machine, or an external dead-man's-switch service that pages you when the ping stops.

With that in place, an error workflow is still worth attaching for loud failures. Set one in workflow settings using an Error Trigger node, and make the alert name the workflow, the node, and the input — a bare "workflow failed" with no context just trains you to ignore alerts. Route it to Slack or Telegram.

Frequently asked questions

Why does my workflow work when I click Execute but not on its own?
Manual execution and production execution are separate. Publish the workflow, and make sure it has a trigger other than the Manual Trigger.

Why did my webhook work for two minutes and then stop?
That was the test URL, which listens for 120 seconds. Use the production URL for anything external.

My scheduled workflow skipped a night. Where did it go?
The instance was probably down when the run was due. The default in-memory scheduler skips missed runs rather than catching them up. The durable scheduler changes that, but it's off by default.

Can two workflows use the same webhook path?
No — one webhook per path and method. Change the path or unpublish the other workflow.

Do I have to republish after every edit?
Yes, for the change to affect production runs. And for Schedule Triggers, publishing restarts the interval from that moment.

How do I see what a production webhook received?
Not in the editor — that's test-URL behavior. Open the execution in the executions list and inspect the trigger node's output.

Where did the Active toggle go?
It was replaced. Publishing a workflow is what makes it live now. Tutorials showing a toggle on an empty canvas predate the change.

Why can't I click Publish?
Usually unsaved changes, or a required field missing in the trigger node. Hover the control for the specific reason.

My workflow runs but processes the same item twice. Is that a trigger problem?
It's a retry. If your workflow is slow to respond, the sender may retry and deliver the same payload again — and nothing errors, because both runs succeed. Write an idempotency key before the irreversible step, not after it, and check it on entry.

Official references worth bookmarking: n8n's Webhook node common issues and Schedule Trigger common issues.

Still stuck? Working starter workflows — including an error-handler and a heartbeat monitor — are on our templates page. If the root cause turned out to be your hosting setup, the self-hosting guide and Docker setup guide cover the URL and proxy configuration properly.

How to Self-Host n8n: A Complete Beginner's Guide (2026)

Ali Ilyas — Wed, 05 Aug 2026 18:19:46 +0000

Originally published at noderecipe.com.

Self-hosting n8n gives you unlimited workflow executions, full ownership of your data, and no per-task fees — all for the cost of a small server (about $5/month). This guide takes you from an empty VPS to a secured, HTTPS-enabled n8n instance running 24/7, using Docker and Docker Compose. You'll also get the environment variables that actually matter, a backup routine, and fixes for the errors that trip up most beginners.

No prior Docker experience is assumed. If you can copy a command into a terminal, you can finish this in about 30 minutes.

Self-hosted vs. n8n Cloud: which do you need?

Before you spin up a server, be honest about which path fits you. n8n offers a paid cloud plan and a free, source-available self-hosted option (the Community Edition). Here's the trade-off:

Factor	Self-hosted (Community)	n8n Cloud
Price	~$5/mo server, unlimited executions	From ~$24/mo, metered executions
Data location	Your server, your control	n8n's managed infrastructure
Maintenance	You handle updates & backups	Fully managed
Setup time	~30 min (this guide)	Minutes
Custom nodes / npm packages	Full control	Limited
Best for	Developers, high-volume, privacy needs	Non-technical users, teams who want zero ops

Choose self-hosting if you run a lot of executions, want your data on infrastructure you control, or need custom community nodes. Choose Cloud if you never want to think about servers — the honest version is that if your automations make you money and your time is worth more than $20/month, managed hosting is the cheaper option however it looks on the invoice. The rest of this guide covers self-hosting.

What you'll need

A VPS (virtual private server) — roughly $5/month. See the comparison below.
SSH access to that server (a terminal on Mac/Linux, or a client like PuTTY/Windows Terminal on Windows).
A domain or subdomain you can point at the server (e.g. n8n.yourdomain.com). This is required for HTTPS and for webhooks to work reliably.
About 30 minutes.

You do not need to know Docker beforehand — every command is provided.

Where to host n8n (VPS comparison)

Any Linux server with 1 GB of RAM will run a small n8n instance, but 2 GB is more comfortable once you have a few active workflows. These are the popular, budget-friendly options:

Provider	Entry price	RAM	Best for
Hetzner Cloud	~€4.5/mo	2–4 GB	Best price-to-performance (EU/US regions)
DigitalOcean	$6/mo	1 GB	Beginner-friendly UI, great docs
Railway	Usage-based	Scales	Fastest setup, no server management
Home server / Raspberry Pi	$0	Varies	Tinkering, LAN-only automations

For most people starting out, Hetzner's CX22 (2 GB RAM) or a DigitalOcean basic droplet is the sweet spot. Pick Ubuntu 24.04 LTS as the operating system when you create the server.

Two notes on picking between them, since this is the one decision that costs money. Hetzner is roughly half the price for double the RAM — a CX22 gives you 2 GB for about €4.5, where DigitalOcean's $6 droplet gives you 1 GB. If you are comfortable in a terminal, Hetzner is the better machine for the money. DigitalOcean is worth the premium if you are new to servers: the control panel is friendlier, and their documentation is genuinely the best in the business for the exact moment when something breaks at 11pm. Both give new accounts a signup credit that covers your first month or two.

Quick start: run n8n in one command

Want to see n8n before committing to the full setup? SSH into your server and run:

docker volume create n8n_data

docker run -d --restart unless-stopped --name n8n \
  -p 5678:5678 \
  -v n8n_data:/home/node/.n8n \
  docker.n8n.io/n8nio/n8n

Open http://your-server-ip:5678 in your browser and create your owner account. That's a working n8n — but it has no HTTPS, no database, and no domain, so webhooks and OAuth logins will misbehave. Treat this as a test drive, then move to the production setup below.

Don't have Docker yet? Install it in one line: curl -fsSL https://get.docker.com | sh

Production setup with Docker Compose

Docker Compose lets you define n8n, a PostgreSQL database, and a reverse proxy in a single file so they start together and survive reboots. This is the setup you actually want to keep.

Step 1: Install Docker and Compose

On a fresh Ubuntu server, run:

curl -fsSL https://get.docker.com | sh

The Compose plugin ships with modern Docker. Verify both:

docker --version
docker compose version

Step 2: Point your domain at the server

In your DNS provider (Cloudflare, Namecheap, etc.), create an A record for n8n.yourdomain.com pointing to your server's public IP. DNS can take a few minutes to propagate — you can continue while it does.

Step 3: Create the project folder

mkdir -p ~/n8n && cd ~/n8n

Step 4: Create the `.env` file

This holds your secrets and settings. Create ~/n8n/.env:

# --- Your domain ---
DOMAIN_NAME=n8n.yourdomain.com

# --- Database (Postgres) ---
POSTGRES_USER=n8n
POSTGRES_PASSWORD=change-this-to-a-long-random-string
POSTGRES_DB=n8n

# --- n8n security ---
# Generate with: openssl rand -hex 32
N8N_ENCRYPTION_KEY=paste-a-32-byte-random-hex-string-here
GENERIC_TIMEZONE=America/New_York

Generate strong values before saving:

openssl rand -hex 32   # use for N8N_ENCRYPTION_KEY
openssl rand -hex 16   # use for POSTGRES_PASSWORD

Keep N8N_ENCRYPTION_KEY safe. It encrypts all your saved credentials. If you lose it, every stored credential becomes unreadable and you'll have to re-enter them.

Step 5: Create `docker-compose.yml`

Create ~/n8n/docker-compose.yml:

services:
  postgres:
    image: postgres:16
    restart: unless-stopped
    environment:
      - POSTGRES_USER=${POSTGRES_USER}
      - POSTGRES_PASSWORD=${POSTGRES_PASSWORD}
      - POSTGRES_DB=${POSTGRES_DB}
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER} -d ${POSTGRES_DB}"]
      interval: 10s
      timeout: 5s
      retries: 5

  n8n:
    image: docker.n8n.io/n8nio/n8n:latest
    restart: unless-stopped
    depends_on:
      postgres:
        condition: service_healthy
    environment:
      - DB_TYPE=postgresdb
      - DB_POSTGRESDB_HOST=postgres
      - DB_POSTGRESDB_DATABASE=${POSTGRES_DB}
      - DB_POSTGRESDB_USER=${POSTGRES_USER}
      - DB_POSTGRESDB_PASSWORD=${POSTGRES_PASSWORD}
      - N8N_ENCRYPTION_KEY=${N8N_ENCRYPTION_KEY}
      - N8N_HOST=${DOMAIN_NAME}
      - N8N_PROTOCOL=https
      - N8N_PORT=5678
      - WEBHOOK_URL=https://${DOMAIN_NAME}/
      - GENERIC_TIMEZONE=${GENERIC_TIMEZONE}
      - N8N_RUNNERS_ENABLED=true
    volumes:
      - n8n_data:/home/node/.n8n
    expose:
      - 5678

  caddy:
    image: caddy:2
    restart: unless-stopped
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile
      - caddy_data:/data
      - caddy_config:/config
    depends_on:
      - n8n

volumes:
  postgres_data:
  n8n_data:
  caddy_data:
  caddy_config:

Note that n8n uses expose (internal only) rather than publishing port 5678 to the public internet — Caddy is the only service that faces the outside world.

The environment variables that matter

Most self-hosting problems come from missing or wrong environment variables. These are the ones you should always set on a production instance:

Variable	Why it matters
`N8N_ENCRYPTION_KEY`	Encrypts stored credentials. Set it explicitly and back it up.
`N8N_HOST` / `WEBHOOK_URL`	Must match your real domain, or webhooks and OAuth callbacks break.
`N8N_PROTOCOL=https`	Tells n8n it's served over HTTPS (behind the proxy).
`DB_TYPE=postgresdb`	Uses Postgres instead of the default SQLite — required for reliability at scale.
`GENERIC_TIMEZONE`	Makes Schedule/Cron nodes fire at the times you expect.
`N8N_RUNNERS_ENABLED=true`	Enables task runners, the recommended way to execute Code nodes. Required on n8n 1.x; deprecated from version 2.0, where it's on by default and can be omitted.

One more worth knowing about if you import workflows you didn't write: N8N_BLOCK_ENV_ACCESS_IN_NODE defaults to false, which means Code nodes and expressions can read your environment variables — including the encryption key and database password above. Setting it to true closes that off. Importing templates safely covers why that matters and what else to check before running someone else's workflow.

Adding HTTPS with Caddy

Caddy provisions and renews a free Let's Encrypt certificate automatically — no manual certbot steps. Create ~/n8n/Caddyfile:

n8n.yourdomain.com {
    reverse_proxy n8n:5678
}

Replace n8n.yourdomain.com with your real subdomain (it must match DOMAIN_NAME). That's the entire config — Caddy handles the TLS certificate the first time someone hits the domain.

Now start everything:

cd ~/n8n
docker compose up -d

Give it a minute (the certificate is issued on first request), then open https://n8n.yourdomain.com. Create your owner account and you're live — with a valid HTTPS padlock.

Check that all three containers are healthy:

docker compose ps

Keeping n8n running, updated, and backed up

Auto-restart: restart: unless-stopped in the Compose file means Docker brings your containers back after a crash or server reboot. Nothing else needed.

Updating n8n: pull the newest image and recreate the container. Your data lives in named volumes, so it survives the upgrade:

cd ~/n8n
docker compose pull
docker compose up -d

Backups — do not skip this. Your workflows and credentials live in Postgres and the n8n volume. Back up the database regularly:

docker compose exec -T postgres \
  pg_dump -U n8n n8n > ~/n8n-backup-$(date +%F).sql

Copy that .sql file off the server (to your machine, S3, or a backup service) and keep your .env alongside it — remember, without N8N_ENCRYPTION_KEY the backup's credentials can't be decrypted. Automate it with a daily cron job for peace of mind.

Securing your instance

A public n8n instance is a target. Lock it down:

Firewall: allow only ports 22 (SSH), 80, and 443. On Ubuntu: ufw allow 22 && ufw allow 80 && ufw allow 443 && ufw enable.
Never expose port 5678 directly. Let Caddy terminate TLS; keep n8n internal (as configured above).
Use strong, unique secrets for the database password and encryption key.
Keep the server updated: apt update && apt upgrade -y periodically.
Restrict SSH to key-based auth and disable root password login.

Common errors and fixes

"This site can't provide a secure connection" / no HTTPS.
DNS isn't pointing at your server yet, or port 80/443 is blocked. Confirm the A record resolves (dig n8n.yourdomain.com) and that your firewall/cloud security group allows 80 and 443. Caddy needs port 80 reachable to issue the certificate.

Webhooks return the wrong URL or don't fire.
WEBHOOK_URL and N8N_HOST must match your public HTTPS domain exactly. If they still show localhost or an IP, you edited the values but didn't recreate the container — run docker compose up -d again.

"Command 'code' is not allowed" or Code node fails.
On n8n 1.x, enable task runners with N8N_RUNNERS_ENABLED=true (already in the Compose file above) and restart. On 2.0 and later, task runners are enabled by default and that variable is deprecated — if the error persists there, check the container logs instead.

Credentials show as "unable to decrypt."
The N8N_ENCRYPTION_KEY changed between runs. It must stay identical to the one used when the credentials were saved. Restore the original key from your backup.

Containers keep restarting.
Check logs to see which one: docker compose logs n8n --tail=50 or docker compose logs postgres --tail=50. The most common cause is a Postgres password mismatch after editing .env without recreating the database volume.

Schedule/Cron node fires at the wrong time.
Set GENERIC_TIMEZONE to your IANA timezone (e.g. Europe/London) and restart.

Frequently asked questions

Is self-hosting n8n free?
The n8n Community Edition is free to self-host, permanently and with no execution limit. Your only cost is the server (~$5/month) and your domain. One caveat worth knowing before you build a business on it: n8n is source-available, not open source, and its Sustainable Use License restricts hosting n8n for paying users. What's free and what isn't breaks that down, including what it means for client work.

Do I need a domain?
For a real setup, yes. Webhooks, OAuth logins, and HTTPS all depend on a proper domain. You can test on a raw IP, but production needs a domain. Google's OAuth flow makes this concrete: the redirect URI is registered against one fixed address, so connecting a service like Google Sheets means re-registering it every time your instance moves.

SQLite or Postgres?
n8n defaults to SQLite, which is fine for testing. For anything you rely on, use Postgres (as in this guide) — it handles concurrent executions far more reliably.

How much RAM do I need?
1 GB runs a light instance; 2 GB is comfortable for regular use with several active workflows. Heavy AI or data workflows benefit from more.

How do I move from n8n Cloud to self-hosted?
Export your workflows as JSON from Cloud and import them into your self-hosted instance, then re-enter credentials. Your workflows are portable JSON either way.

Ready to build? The docker-compose.yml and Caddyfile above are ready to copy as they stand. Once the instance is up, our templates page has eight importable workflows to run on it — error handling, monitoring, and AI starters. New to containers, or want the details on volumes, image tags, and safe updates? Start with the n8n Docker setup guide.

DEV Community: Ali Ilyas

n8n Docker Setup: Run n8n in a Container Without Losing Your Data (2026)

Do you want Docker setup, or full self-hosting?

What you'll need

Start n8n in one command

Where n8n stores your data

docker run vs. Docker Compose

A Compose file for everyday local use

The environment variables that matter

Updating n8n, and rolling back

Docker Desktop on Windows and macOS

Common Docker errors and fixes

Frequently asked questions

n8n Telegram Bot: Build One That Sends and Receives Messages (2026)

What you'll need

Create the bot with BotFather

Add the credential in n8n

Send your first message

Finding your chat ID

Formatting messages without breaking them

Receiving messages with the Telegram Trigger

The one-webhook-per-bot problem

Buttons, replies, and inline keyboards

Sending photos and files

Common errors and fixes

Frequently asked questions

n8n Google Sheets Integration: Connect, Read, and Write Rows (2026)

What you'll need

Connecting Google Sheets to n8n

Setting up custom OAuth2, step by step

1. Create a Google Cloud project

2. Enable both APIs

3. Configure the OAuth consent screen

4. Create the OAuth client

5. Finish in n8n

When to use a service account instead

The operations, and which one you want

Build 1: append incoming data to a sheet

Build 2: read rows and filter them

Build 3: update a row instead of duplicating it

Triggering a workflow when a row is added

Gotchas that cost people hours

Frequently asked questions

n8n Workflow Not Triggering? Work Through It in This Order (2026)

Start here: is the workflow published?

The Publish control is greyed out or missing

Are you using the test URL or the production URL?

Read the executions list before anything else

It works when I run it manually

Webhook triggers

Schedule triggers

App triggers: Telegram, Slack, Google Sheets

Self-hosted-only causes

It triggers, but nothing happens

Make the next failure visible

Frequently asked questions

How to Self-Host n8n: A Complete Beginner's Guide (2026)

Self-hosted vs. n8n Cloud: which do you need?

What you'll need

Where to host n8n (VPS comparison)

Quick start: run n8n in one command

Production setup with Docker Compose

Step 1: Install Docker and Compose

Step 2: Point your domain at the server

Step 3: Create the project folder

Step 4: Create the .env file

Step 5: Create docker-compose.yml

The environment variables that matter

Adding HTTPS with Caddy

Keeping n8n running, updated, and backed up

Securing your instance

Common errors and fixes

Frequently asked questions

Step 4: Create the `.env` file

Step 5: Create `docker-compose.yml`