Why your Sheets writes are duplicating
The most common n8n-to-Sheets failure is not that the write fails. It is that the write succeeds twice. Three events produce the second row for the same lead:
- A webhook retry. The Google Sheets node returned a 5xx (or timed out at the provider), the caller re-sent the identical payload, and n8n ran the whole thing again.
- A manual test. You clicked "Execute workflow" to check the output, and the test ran the real Sheet-write node. Later, the scheduled run wrote the same row again.
- A restarted instance. A run that was mid-send when the VPS restarted filed the same write twice across the restart boundary.
n8n has no memory of the first write. It sees a new trigger payload and starts a new execution. The only thing standing between you and a growing pile of duplicate rows is an upsert: a check-then-write that refuses to insert a row whose business key already exists.
The two rules are simple. Write them on a sticky note.
- Key on a business value, never on the row number. Row numbers move when someone sorts or filters the sheet. A customer's email, invoice number, or lead ID does not.
- Write every time, but make writes idempotent. Upsert on every run. The check then insert path, and the skip path, must both end cleanly.
The check-then-write pattern, step by step
You need three things in one execution: look up whether the business key exists, branch on the answer, and write. The cleanest way is a small skeleton that you copy into every workflow that writes to your sheet.
Step 1: Build a key node
Right after the trigger (webhook, schedule, or manual), add a Code node that builds a single string from your business key. For a lead list that is usually the email address; for an invoice dunning workflow it is the invoice number. Keep the key stable: lowercase and trim the email, and do not change the format between runs.
// Code node: build the business key
const email = $json.email ? $json.email.trim().toLowerCase() : '';
const key = email || 'unknown:' + $json.full_name + ':' + $json.source;
return [{ json: { sheet_key: key, source: $json } }];
If your payload has a stable ID (Stripe id, Shopify X-Shopify-Event-Id, GitHub X-GitHub-Delivery), use that instead — it is unique across the entire platform, not just your own workflows.
Step 2: Look up the row
Two options, chosen by how many rows you expect.
Small or medium sheets (under ~10,000 rows). Use a Google Sheets node in Read mode with Range A:E and a Filter on the email column. It is simple and is the one the n8n template library uses. The filter is the important part — filtering on the sheet itself costs a round-trip to Google, so do it in the node, not in a Code node.
Large sheets or high write volume. Use the Lookup node (or a Data Table). A Lookup node is faster than a Google Sheets read because it queries n8n's own local database instead of hitting Google's API, so you save on quota and latency.
// Code node: check if the key exists
const existing = await $workflow.parameters.sheet_rows || [];
const match = existing.find(r => r.email === $json.email);
return [{ json: { already_exists: !!match, row: match } }];
The lookup must run before the first node that touches the outside world. If you place it after the email-send node, you have already duplicated the side effect.
Step 3: Branch, then write
Use an IF node on the already_exists flag.
New lead: connect the "no match" branch to the rest of your workflow, ending in a Google Sheets node with operation Create (or Append). The sheet row must include every column the sheet expects. A row missing a column will be written as null or rejected with a cryptic error.
Already known: connect the "match found" branch to a Google Sheets node with operation Update. This is where you update the existing row's updated fields — say, last_contacted and status — and leave the untouched columns alone.
Do not use a separate Get Row then Update as two steps. One Update call with the full row replaces the whole row, and a JSON node between the lookup and the update is the only way to carry the existing values forward safely.
Write every time — but make the write idempotent
The trap is to skip the write on the "already exists" branch, thinking "nothing to do". n8n no longer runs the workflow for that pagination window, but the caller does not know that. The fix is to run the full write path on every execution — the row you update is the row you just read. The update is a no-op if nothing changed, which is harmless.
The pattern, in full:
[Webhook / Schedule / Manual Trigger]
|
v
[Code: build sheet_key]
|
v
[Google Sheets: Read] // or Lookup/Code — columns A:Z
|
v
[If: sheet_key === row.email]
|
+-- NO --> [Code: current = row (copy)]
| [Code: merged = Object.assign({}, current, $json)]
| [Google Sheets: Update row]` // operation = update
| // end workflow
|
+-- YES --> [Code: new row = merge(current, $json)]
[Google Sheets: Append] // operation = create
// end workflow
The copy-then-merge step is the one people skip, and it is why updates silently drop fields. If your sheet has 14 columns and your workflow only touches three, a plain Append adds a row missing eleven columns. The copy pulls the existing row, the merge overlays the new fields, and the update replaces the whole row with a complete one.
Use the same key for the read as for the write. If you look up by email but write by name, you will keep creating duplicate rows on customers whose name changes or who type their email differently each time.
Upsert for existing rows: the exact code
For the "already exists" branch, this Code node produces the merged row you then pass to the Update node:
// Code node: merge new fields on top of the existing row
const existing = $json.row || {};
const merged = Object.assign({}, existing, $json);
// always refresh the updated timestamp
merged.updated_at = new Date().toISOString();
return [{ json: merged }];
Then the Google Sheets node, configured exactly like this:
- Operation: Update
- Sheet name: the sheet you write to (add
!A:Zif your sheet is a specific tab) - Range: the address of the existing row, e.g.
B2:N2— the first cell is the row you matched, and the range covers every column - Extra columns: only the columns you want to set; the two code nodes above set the rest
A common misconfiguration is leaving "Extra columns" populated with the overwritten values. The Update node will write those back again, clobbering your computed fields. Leave it empty.
The three most common mistakes
- Writing with $json instead of ${(workflow.parameters.sheet_rows || [])}. The trigger payload is the webhook body, which may contain only some fields. The row you read from the sheet is the full record, and it is what you must carry forward.
- Filtering the sheet by row number. "Get rows 5 to 5" breaks the moment your sheet is sorted, and it never finds rows you appended above. Filter by content, never by position.
- Trusting the sheet to dedupe. Google Sheets has no built-in dedup. A
UNIQUEformula in a helper column can catch duplicates after the fact, but it cannot stop the write; it only cleans up afterward. The guard belongs in n8n.
When you should not use a sheet at all
If your list exceeds ~20,000 rows, or you need to query it by several different keys, a spreadsheet is the wrong store and n8n's database is a better one. The same upsert pattern maps directly to a Supabase table (with a unique constraint on the key column) or a Data Table — both index the lookup and both reject duplicate inserts on their own. The n8n template library ships a "Sheets as DB" template that shows the same skeleton against Supabase, so switching storage later is a node swap, not a rewrite.
Want the workflow, not the write-up?
Every Matemplates workflow imports into your own n8n instance — you own it, run it free, and edit it. Grab the Sheets upsert template and ship today.
Browse the store →