node cookbook

n8n Split In Batches / Loop Over Items: Production Loop Checklist

Use Split In Batches, now documented as Loop Over Items, when a workflow needs controlled batches for rate limits, large item lists, or memory pressure. First prove the loop exits, the final partial batch runs, and retries cannot duplicate side effects.

Match your incident first

Start with the symptom you can prove

Jump to checks

Workflow never reaches the final summary or done step

First check: Run a small list of 3 items with batch size 2 and watch whether the done output runs after the second batch.

Wrong fix to avoid: Do not raise the batch size to escape the loop; fix the loop wiring and exit condition first.

Verify: The execution processes batches of 2 and 1, then runs the done path exactly once.

HTTP Request returns 429 or provider rate limit errors

First check: Reduce batch size and add a Wait or provider-specific retry delay before re-running a safe sample.

Wrong fix to avoid: Do not blindly retry the full failed execution if the downstream API already accepted some items.

Verify: A sample execution finishes without 429 responses and the provider dashboard shows expected request pacing.

Memory usage stays high even after adding Loop Over Items

First check: Test a production-style run with smaller upstream fetches or sub-workflows that return only compact batch results.

Wrong fix to avoid: Do not assume looping alone frees memory if the main workflow still carries the full payload through every node.

Verify: Execution data is smaller and the run completes without out-of-memory symptoms.

Use when: n8n workflows, batch processing, loops, rate-limited APIs, large item lists
First check: Place Loop Over Items after the node that outputs the full item list.
Time to check: 5-10 minutes
Next step: Run the recommended steps, then verify a production execution.

Independent third-party notes. n8n is a trademark of its owner and is referenced only for compatibility and troubleshooting context.

Quick Answer

Problem Pattern

A production workflow handles a large list, external API, database write, or enrichment loop, but it either times out, hits 429 responses, consumes too much memory, repeats items, or never reaches the done path.

Key Facts

Node role: Loop through incoming items in smaller batches and continue through a done path after all items are processed.
Best fit: Rate-limited APIs, large lists, database updates, enrichment jobs, and workflows that should avoid processing every item at once.
Common benefit: More controlled external API calls and a way to split heavy processing into smaller work units.
Common companion nodes: HTTP Request, Code, database nodes, IF, and Wait.
Not always needed: Many n8n nodes already run once for each input item, so add Loop Over Items only when you need explicit batching, pacing, or loop-level control.

Production Diagnostic Matrix

Turn checks into a brief

Exact symptom or log	Likely cause	First check	Wrong fix to avoid	Verification
Workflow never reaches the final summary or done step	Loop output is wired back incorrectly, Reset is used without an exit condition, or a branch keeps returning items to the loop.	Run a small list of 3 items with batch size 2 and watch whether the done output runs after the second batch.	Do not raise the batch size to escape the loop; fix the loop wiring and exit condition first.	The execution processes batches of 2 and 1, then runs the done path exactly once.
HTTP Request returns 429 or provider rate limit errors	Batches are still too large, parallelism is too high, or there is no Wait/backoff between provider calls.	Reduce batch size and add a Wait or provider-specific retry delay before re-running a safe sample.	Do not blindly retry the full failed execution if the downstream API already accepted some items.	A sample execution finishes without 429 responses and the provider dashboard shows expected request pacing.
Memory usage stays high even after adding Loop Over Items	The workflow still holds a very large upstream payload, binary data, Code node output, or manual execution data.	Test a production-style run with smaller upstream fetches or sub-workflows that return only compact batch results.	Do not assume looping alone frees memory if the main workflow still carries the full payload through every node.	Execution data is smaller and the run completes without out-of-memory symptoms.
Rows, emails, Slack messages, or API records are duplicated after retry	The loop performs side effects without an idempotency key, processed marker, or unique constraint.	Add a stable source ID or processed flag before re-running any partially completed batch.	Do not rerun from the first item unless downstream writes are safe to repeat.	Retrying the same batch updates or skips existing records instead of creating duplicates.

Recommended Steps

Place Loop Over Items after the node that outputs the full item list.
Choose a small batch size based on the slowest downstream limit, not the fastest successful manual test.
Put only the batch processing nodes inside the loop path, then connect the loop back correctly.
Add Wait, retry, or backoff inside the loop only when the external API or database needs pacing.
Make the write side idempotent before retrying partially completed batches.
Run a test list whose item count is not divisible by the batch size so the final partial batch is verified.
Confirm the done output runs once and the execution summary matches the expected item count.

Verification

All expected items are processed exactly once.
API rate limit errors decrease or disappear.
Workflow memory usage is lower than processing the full list at once.
The done path runs once after the last partial batch.
A retry of one failed batch does not duplicate external writes, messages, or database rows.

First Commands / Checks

Small uneven batch smoke test Use before running a production list or after changing loop wiring.

Input items: 5
Batch size: 2
Expected loop batches: 2, 2, 1
Expected done path: runs once after item 5

Secrets note: Use dummy item IDs or redacted payloads; do not paste customer data into test notes.
Verification: Execution history shows every test item once and the done output fires once.

Retry safety check Use before retrying a failed loop that writes to an API, database, email, or Slack.

Dedupe key present: yes
Processed marker or unique constraint: yes
Failed batch range known: yes
Full rerun safe: no, unless writes are idempotent

Secrets note: Keep API keys, access tokens, and full customer payloads out of screenshots and shared logs.
Verification: A repeated item is skipped, updated, or rejected by a unique key instead of duplicated.

Warnings

Batch processing can still create duplicate side effects if retries are not idempotent.
A very large batch size may not reduce memory or API pressure enough.
Do not enable Reset without a clear exit condition; resetting loop state can create an infinite loop.
Avoid using manual executions as the only proof for large data; n8n documents that manual runs can use more memory because data is copied for the frontend.

Common Mistakes

Setting batch size too high and still hitting memory or API limits.
Forgetting idempotency before retrying a partially completed batch.
Not testing the final partial batch.
Building a loop that never reaches completion.
Adding Loop Over Items around a node that already processes each input item when no pacing or batch-level control is needed.
Putting summary or notification nodes inside the loop path when they should run once after the done output.

Examples

Batch an API enrichment workflow Reduce pressure on external APIs and n8n memory.

Input: 1,000 leads
Batch size: 25
Inside loop: HTTP Request -> Set -> database update with lead_id as dedupe key -> Wait if provider needs pacing
Done path: Slack summary with processed, skipped, and failed counts

Verify the final partial batch Catch off-by-one and wrong done-path wiring before production.

Input: 7 records
Batch size: 3
Expected: batch 1 has 3 records, batch 2 has 3 records, batch 3 has 1 record, done path runs once

FAQ

Does batching make a workflow faster?

Not always. It usually makes the workflow more controlled and reliable, especially with large data or rate-limited APIs.

What batch size should I use?

Start small enough to avoid API and memory pressure, then increase after measuring execution time and failure rate.

Why does the workflow keep looping forever?

Check the loop wiring, Reset usage, and branch conditions with a tiny uneven test list. The done output should run once after the final partial batch.

Is Loop Over Items the same as making every node run once per item?

No. Many n8n nodes already handle each input item. Loop Over Items is mainly useful when you need explicit batching, pacing, or loop-level control.

Sources

n8n Loop Over Items Node Accessed 2026-06-09 n8n Memory-related Errors Accessed 2026-06-09