Jawaban singkat: error n8n bot WhatsApp terbagi 5 kategori — (1) Infrastructure (VPS, Docker, Network), (2) WhatsApp Connection (QR, Token, Webhook), (3) AI Integration (API Key, Rate Limit, Model), (4) Workflow Logic (Expression, Node Error, Data), (5) Performance (Memory, CPU, Queue). Artikel ini troubleshooting visual per error code, root cause, dan fix step-by-step.
Metodologi Troubleshooting n8n (Visual & Sistematik)
🔍 4 LANGKAH DIAGNOSIS (Ikuti Berurutan):
- CEK EXECUTION LOG: n8n → Executions → Klik error (merah) → Baca **Node yang error** + **Error Message** + **Input/Output Data**
- IDENTIFIKASI KATEGORI: Cocokkan error message ke 5 kategori di bawah
- APPLY FIX: Ikuti step-by-step per error code
- VERIFIKASI: Re-run execution gagal / Kirim test chat → Pastikan hijau
Kategori 1: Infrastructure Errors (VPS, Docker, Network)
| Error / Gejala | Root Cause | Fix Step-by-Step |
|---|---|---|
| n8n tidak bisa diakses (Browser: “Connection Refused” / “Site Can’t Be Reached”) | 1. n8n container stopped/crashed 2. Nginx tidak jalan / config salah 3. Port 5678 tidak expose / firewall block 4. Domain DNS tidak arah ke IP VPS 5. SSL Cert expired / Nginx SSL config error |
1. `docker compose -f /opt/n8n/docker-compose.yml ps` → cek status n8n, nginx, postgres, redis 2. Kalau n8n `Exit 1` / `Restarting`: `docker compose logs n8n –tail=50` → cek error 3. `systemctl status nginx` → restart: `systemctl restart nginx` 4. `ufw status` → pastikan 80,443,22 allow 5. `curl -I https://domain-anda.com` → cek response 6. SSL: `certbot certificates` → renew: `certbot renew –force-renewal` + `nginx -s reload` |
| Docker Container Keep Restarting (Restarting / Exited) | 1. Out of Memory (OOM Killer) 2. Config error (env variable salah) 3. Database connection failed (postgres/redis not ready) 4. Volume permission error 5. Port conflict (5678 sudah dipakai) |
1. `docker compose logs n8n –tail=100` → cari “OOMKilled” / “permission denied” / “ECONNREFUSED” 2. OOM: Upgrade VPS RAM / Tambah Swap: `fallocate -l 2G /swapfile && chmod 600 /swapfile && mkswap /swapfile && swapon /swapfile` 3. Env: Cek `/opt/n8n/.env` → pastikan semua variable ada, password kuat, domain benar 4. Depends_on: Pastikan postgres & redis `healthcheck` pass sebelum n8n start 5. Permission: `chown -R 1000:1000 /opt/n8n/data` 6. Port: `netstat -tulpn | grep 5678` → kill process lain |
| VPS Disk Full (“No space left on device”) | 1. Docker logs tidak di-rotate (default json-file unlimited) 2. PostgreSQL WAL / data growth 3. n8n executions history tidak di-purge 4. Backup files tidak di-cleanup 5. /tmp / /var/log penuh |
1. `df -h` → cek partisi penuh 2. Docker log rotate: `/etc/docker/daemon.json` → `{“log-driver”:”json-file”,”log-opts”:{“max-size”:”10m”,”max-file”:”3″}}` → `systemctl restart docker` 3. `journalctl –vacuum-time=7d` 4. n8n: Settings → Executions → Retention: 30 hari / Max 10000 5. Cleanup backup: `find /opt/n8n/backups -mtime +30 -delete` 6. PostgreSQL: `docker compose exec postgres psql -U n8n -d n8n -c “VACUUM FULL;”` |
| SSL Certificate Error / Expired | 1. Let’s Encrypt cert expired (90 hari) 2. Auto-renewal cron tidak jalan 3. Nginx config tidak include cert baru 4. Domain tidak resolve ke IP VPS (DNS issue) |
1. `certbot certificates` → cek expiry 2. Manual renew: `certbot renew –force-renewal –dry-run` → kalau OK: `certbot renew –force-renewal` 3. `nginx -s reload` setelah renew 4. Auto-renewal cron: `crontab -l` → pastikan ada `certbot renew` + `nginx -s reload` 5. DNS: `dig domain-anda.com` → pastikan A Record = IP VPS |
Kategori 2: WhatsApp Connection Errors
| Error / Gejala | Root Cause | Fix Step-by-Step |
|---|---|---|
| WhatsApp Trigger: “Unauthorized” / “Session Closed” / “QR Expired” | 1. Gateway Praktis: QR expired (30-90 hari) 2. WhatsApp Web logout di HP / Device limit (max 4) 3. Gateway server restart / maintenance 4. API Resmi: Access Token expired / revoked 5. Phone Number ID salah / tidak match |
Gateway Praktis: 1. Dashboard Gateway → “Reconnect” / “Scan QR Ulang” 2. n8n: Re-execute Trigger node / Restart workflow 3. HP: WhatsApp → Linked Devices → Hapus device lama → Scan QR baru 4. Pilih gateway dengan “Keep Alive” / Auto-reconnect API Resmi: 1. Meta Business Manager → System User → Generate New Token 2. n8n Credential: Update Access Token baru 3. Cek Phone Number ID match WABA |
| Webhook Verification Failed (Meta API Resmi) | 1. Callback URL tidak HTTPS / SSL invalid 2. Domain tidak resolve / IP salah 3. n8n tidak respond challenge GET (timeout / 404 / 500) 5. Verify Token salah |
1. `curl -X GET “https://domain-anda.com/webhook/whatsapp?hub.mode=subscribe&hub.challenge=test123&hub.verify_token=TOKEN_ANDA”` → harus return `test123` (200 OK) 2. n8n: Pastikan WhatsApp Trigger node aktif & workflow Active 3. Nginx: Pastikan proxy_pass ke n8n:5678, WebSocket support 4. SSL: Valid Let’s Encrypt / Cloudflare Full SSL 5. Verify Token: Sama persis di Meta & n8n Trigger settings |
| Template Rejected / Not Approved (API Resmi) | 1. Kategori salah (Marketing di Utility / sebaliknya) 2. Variable format salah (`{{1}}` bukan `{1}` / `{{name}}`) 3. Konten promotional di kategori Utility 4. Bahasa tidak didukung / karakter aneh 5. Duplicate template name |
1. Baca alasan reject di Meta: “Template rejected: [Reason]” 2. Utility: Hanya transaksional (OTP, notifikasi order, shipping). Marketing: Promo, broadcast. 3. Variable: Harus `{{1}}`, `{{2}}` urut. Body: “Halo {{1}}, order {{2}} dikirim.” 3. Jangan kata “promo”, “diskon”, “beli sekarang” di Utility. 4. Nama template unique: `order_confirmation_v2` |
| Gateway: “Rate Limit Exceeded” / “Blocked” / “Banned” | 1. Kirim terlalu cepat (blast massal) 2. Pola tidak natural (instan reply, tidak delay) 3. Konten spam / promosi berlebihan 4. Nomor baru langsung volume tinggi 5. User report spam / block |
1. STOP broadcast massal → Hanya balas chat masuk (Service Conversation) 2. Delay random 2-5 detik SETIAP kirim (Node Wait: `Math.random()*3000+2000`) 3. Limit harian: Max 200-500 kirim/hari per nomor (gateway dependent) 4. Warm-up nomor baru: Minggu 1: 50/hari, Minggu 2: 100/hari, dst 4. Opt-out: “Balas STOP untuk berhenti” → Hormati instan 5. Banned: Beli nomor baru, migrasi data, jangan repeat pola lama |
Kategori 3: AI Integration Errors
| Error / Gejala | Root Cause | Fix Step-by-Step |
|---|---|---|
| AI: “Invalid API Key” / “Authentication Error” / “401 Unauthorized” | 1. API Key salah copy / typo 2. API Key revoked / regenerated 3. Organization / Project salah (OpenAI multi-org) 4. Credential n8n tidak ter-update |
1. Copy ulang API Key dari provider dashboard (OpenAI: platform.openai.com/api-keys) 2. n8n → Credentials → AI Credential → Paste key baru → Save → Test 3. OpenAI: Cek Organization ID di URL / Settings → Pastikan match 4. Restart workflow setelah update credential |
| AI: “Rate Limit Exceeded” / “429 Too Many Requests” | 1. Request > RPM limit provider (OpenAI: 3k RPM paid, 60 RPM free) 2. Burst chat (flash sale, broadcast) 3. Tidak ada rate limiter di n8n |
1. Implement Rate Limiter (Function Node: max 20 RPM, queue) 2. Concurrency Limit: `EXECUTIONS_PROCESS=queue` atau `N8N_CONCURRENCY_LIMIT=5` 3. Fallback Provider: OpenRouter / Groq (limit lebih tinggi) 4. Hybrid Static FAQ: 40% chat bypass AI total 5. Upgrade plan provider / Beli quota tambahan |
| AI: “Insufficient Quota” / “Quota Exceeded” / “Billing Error” | 1. Kredit habis (prepaid)\n2. Billing failed (kartu expired, limit)\n3. Free trial habis ($5 OpenAI)\n4. Monthly limit reached | 1. Provider Dashboard → Billing → Topup / Update Payment Method\n2. Auto-recharge ON + Alert email\n3. Fallback ke Provider gratis/murah: OpenRouter (free models), Groq (free tier)\n4. Switch Model Hemat: Llama 3.1 8B / Gemma 2 9B via OpenRouter/Groq\n5. Static FAQ Mode: Bypass AI total untuk FAQ standar |
| AI: “Context Length Exceeded” / “Max Tokens Exceeded” | 1. System Prompt terlalu panjang (>8k/32k/128k tergantung model)\n2. Knowledge Base include semua di prompt\n3. Conversation History terlalu panjang (Memory >10 turno)\n4. Few-shot examples terlalu banyak | 1. Prompt Compression: KB di Sheets (bukan di prompt), Memory 3-5 turno, Few-shot 3 contoh\n2. Model dengan context besar: GPT-4o (128k), Gemini 1.5 Pro (1M), Llama 3.1 (128k)\n3. Hybrid Static FAQ: Top 10 FAQ bypass AI\n5. Chunking: Split KB jadi multiple call (Retrieval Augmented) |
| AI: “Model Overloaded” / “Service Unavailable” / “503” | 1. Provider down / maintenance\n2. Terlalu banyak request paralel (capacity)\n3. Regional outage | 1. Fallback Provider Chain: OpenAI → OpenRouter 70B → OpenRouter 8B/Groq → Static FAQ\n2. Exponential Backoff Retry: 1s, 2s, 4s, 8s → Fallback\n3. Alert Telegram: “🚨 AI Provider Down: [Provider] – Switching to Fallback”\n4. Status Page: Cek status.openai.com / status.openrouter.ai |
Kategori 4: Workflow Logic Errors (Expression, Node, Data)
| Error / Gejala | Root Cause | Fix Step-by-Step |
|---|---|---|
| Expression Error: “Cannot read property X of undefined” / “X is not a function” | 1. Data dari node sebelumnya tidak ada / struktur beda 2. Typo di expression: `$json.filed` vs `$json.field` 3. Optional chaining tidak dipakai: `$json.data?.field` 4. Array vs Object confusion |
1. Klik Execution Error → Lihat **Input Data** node yang error → Cek struktur JSON aktual\n2. Debug: Tambah Node **Set** sebelum node error → `test: {{$json}}` → Execute → Lihat output\n3. Pakai Optional Chaining: `$json.data?.field ?? ‘default’`\n3. Cek tipe: `Array.isArray($json.items) ? $json.items[0] : $json.items` |
| Google Sheets: “Permission Denied” / “Unable to parse range” / “Sheet not found” | 1. OAuth token expired / revoked\n2. Spreadsheet ID salah / Sheet name salah (case sensitive!)\n3. Range format salah: `Sheet1!A:Z` vs `Sheet1` 4. Sheet tidak di-share ke email OAuth |
1. n8n → Credentials → Google Sheets OAuth2 → Reconnect (auth ulang)\n2. Cek Spreadsheet ID di URL: `docs.google.com/spreadsheets/d/SPREADSHEET_ID/edit`\n3. Sheet Name: Tab name di bawah (case sensitive: “FAQ_Kebijakan” ≠ “faq_kebijakan”)\n3. Range: Kosongkan untuk baca semua, atau `A:Z` untuk kolom A-Z\n4. Share Spreadsheet ke email OAuth (Editor) |
| IF Node: Condition Tidak Jalan / Selalu True/False | 1. Expression salah: `={{ $json.field == “value” }}` (kurang `=` di awal)\n2. Tipe data beda: String `”123″` vs Number `123`\n3. Case sensitive: `”FAQ”` vs `”faq”`\n4. Null/Undefined handling | 1. Expression WAJIB diawali `={{ … }}` (dua kurung kurawal + sama dengan)\n2. Normalisasi: `String($json.field).toLowerCase() === “faq”`\n3. Null safe: `$json.field ?? “default” === “value”`\n4. Debug: Set Node sebelum IF → `condition: {{$json.field}}` → Execute → Lihat value |
| Merge Node: Data Tidak Gabung / Duplicate / Missing | 1. Mode salah: `Wait for All` vs `Choose First` vs `Append`\n2. Input tidak sinkron (satu jalur error, tidak sampai Merge)\n3. Key tidak match untuk `Merge By Key` | 1. Mode: `Choose First` (untuk router 6 jalur converge) / `Append` (untuk loop)\n2. Pastikan SEMUA jalur sampai Merge (Error Trigger → handle error → kirim dummy ke Merge)\n3. Merge By Key: Pastikan key sama di kedua input (`$json.id` vs `$json.ID`)\n4. Test: Disable jalur lain → Test satu jalur → Enable semua |
Kategori 5: Performance Errors (Memory, CPU, Queue)
| Error / Gejala | Root Cause | Fix Step-by-Step |
|---|---|---|
| n8n Crash / Restart: “JavaScript heap out of memory” / “OOMKilled” | 1. Execution data terlalu besar (large binary, huge JSON)\n2. Loop tak terbatas / Rekursif\n3. Memory leak di custom Function Node\n4. VPS RAM terlalu kecil (<2GB) | 1. `docker compose logs n8n` → cari “heap out of memory” / “OOMKilled”\n2. Naikkan Node.js Memory: Docker env `NODE_OPTIONS=–max-old-space-size=2048` (2GB) / 4096 (4GB)\n3. Upgrade VPS RAM: 4GB minimum, 8GB recommended\n4. Limit Execution Data: Settings → Executions → `EXECUTIONS_DATA_MAX_AGE=336` (14 hari), `EXECUTIONS_DATA_PRUNE=true`\n4. Custom Function: Hindari large object di memory, gunakan streaming |
| Execution Timeout / Stuck (“Execution took too long” / “Timed out”) | 1. AI Request timeout (default 30s, butuh 60-120s untuk model besar)\n2. HTTP Request ke API lambat (Kurir, Payment, AI)\n3. Loop besar tanpa batch\n4. Deadlock di Merge/Wait | 1. Chat Model Node → Options → Timeout: `120000` (120 detik)\n2. HTTP Request Node → Options → Timeout: `60000` (60 detik)\n3. Loop: Batch Size `10` / `50` (bukan 1 per item)\n3. Merge: Pastikan semua input sampai (Error Trigger → dummy data)\n4. Webhook Timeout: Nginx `proxy_read_timeout 300s; proxy_send_timeout 300s;` |
| Queue Panjang / Execution Pending Banyak (Backlog) | 1. Volume chat > kapasitas proses (Rate Limit AI, Concurrency Low)\n2. Cron Job overlap (Follow-up 30menit masih jalan, yang berikutnya start)\n3. Error berulang → retry loop\n4. VPS CPU 100% | 1. Concurrency: `N8N_CONCURRENCY_LIMIT=10` (naikkan sesuai CPU core)\n2. Cron: `cron` expression → pastikan tidak overlap (Follow-up 30menit, Shipping 15menit – OK beda schedule)\n3. Error Trigger → Fix root cause error → Kurangi retry\n4. VPS: Upgrade CPU / Redis Queue (`EXECUTIONS_MODE=queue` + Redis) |
| Response Time Lambat (>5 detik) tapi tidak Error | 1. AI Model lambat (GPT-4o vs Haiku vs Llama 8B)\n2. Cold Start (n8n idle lama, pertama request lambat)\n3. Database query lambat (PostgreSQL tanpa index)\n4. Network latency (VPS jauh dari user / AI provider) | 1. Model Tiering: FAQ → Llama 8B (Groq/OpenRouter – sub-second), Sales → Haiku/4o-mini\n2. Warm-up: Cron 5 menit hit healthz / dummy request → Keep n8n warm\n3. PostgreSQL: Index pada kolom filter (Nomor_WA, Status, Tanggal)\n4. VPS Lokasi: Pilih region dekat user (Singapura/Jakarta untuk Indonesia)\n4. CDN untuk Gambar: Cloudflare R2 / Bunny.net (bukan Google Drive) |
Quick Reference Card (Print & Tempel di Monitor)
🚨 EMERGENCY QUICK FIX (URUTAN PRIORITAS):
- Bot TOTAL MATI: `docker compose -f /opt/n8n/docker-compose.yml ps` → Restart yang Down → `docker compose up -d`
- Bot DIAM (tidak balas, tidak error): Cek Execution Log → Ada error? → Fix node error → Re-run. Tidak error? Cek WhatsApp Connection (QR/Token) → Reconnect.
- Error 429 / Rate Limit: Tambah Rate Limiter Node → Fallback Provider → Alert Admin.
- Error 401 / Invalid Key: Update Credential di n8n → Save → Test → Restart Workflow.
- Error 503 / AI Down: Fallback Chain otomatis (harus sudah setup) → Alert Admin.
- VPS Disk Full: `journalctl –vacuum-time=3d` + Docker Log Rotate + Cleanup Backup Lama.
- SSL Expired: `certbot renew –force-renewal` → `nginx -s reload`.
- QR Expired: Dashboard Gateway → Scan QR Ulang → Test.
Checklist Troubleshooting Mingguan (Proaktif)
- [ ] Senin: Review Execution Log minggu lalu → Top 5 Error → Fix root cause
- [ ] Selasa: Cek VPS Resource (RAM, CPU, Disk) → Upgrade kalau >80% konsisten
- [ ] Rabu: Cek AI Usage & Cost → Quota aman? Fallback ready? Model tiering optimal?
- [ ] Kamis: Cek WhatsApp Connection Status → QR Valid? Token Valid? Webhook OK?
- [ ] Jumat: Cek Backup Status (GitHub/Drive/S3) → File exists, size > 1KB, Restore test bulan ini?
- [ ] Sabtu: Load Test Mini (10 chat simultan) → Response <2 detik, 0 Error, Queue <5
- [ ] Minggu: Review mingguan: Volume, Response Time, Error Rate, Cost, Conversion → Action Items
FAQ: Solusi Error Umum n8n Bot WhatsApp
Bagaimana cara cepat tahu error apa tanpa buka n8n UI?
Setup Error Trigger Workflow → Telegram Alert Real-time: “🚨 ERROR: Workflow [Nama], Node [Nama], Error: [Pesan], Time: [Waktu]”. Buka HP → lihat notif → tahu error instan. Setup 10 menit, gratis selamanya.
Bot diam tidak balas, tapi n8n Execution tidak ada error (hijau) — kenapa?
Kemungkinan: (1) WhatsApp Send Node sukses tapi WhatsApp tidak terkirim (gateway down / rate limit / banned) → Cek gateway dashboard. (2) Trigger tidak terpicu (webhook URL salah / QR expired / token invalid) → Cek Trigger node execution count. (3) Filter IF node block semua (condition salah) → Debug IF node input.
Apakah butuh programmer untuk fix error n8n?
90% error fixable NON-TEKNIS via n8n UI: Update Credential, Edit Expression, Tambah Node Wait/IF, Reconnect OAuth, Restart Workflow. Programmer butuh: Custom Node development, Complex Function Node debug, Infrastructure (Docker, Nginx, PostgreSQL tuning), Custom API Integration. Bot Supervisor (ex-admin) handle 90% ops.
Bagaimana prevent error sebelum terjadi (proaktif)?
1. Daily Health Check Cron 08:00 → Cek: VPS Resource, WhatsApp Status, AI Quota, Backup Status → Alert kalau anomaly. 2. Weekly Load Test (10 chat) → Verify Response <2s, 0 Error. 3. Monthly DR Drill → Full Restore Test. 4. Alert Threshold: RAM>80%, Disk>85%, CPU>90%, AI Quota<20%, Error Rate>1% → Telegram Alert.
Template troubleshooting lengkap sudah jadi di mana?
Ebook + Template n8n — include: Error Code Dictionary (50+ error code + fix), Troubleshooting Flowchart Visual, Emergency Quick Fix Card, Proactive Monitoring Setup, Weekly/Monthly Checklist, Root Cause Analysis Template, Load Test Script, Performance Tuning Guide, Infrastructure Hardening Guide.
Baca juga: Solusi Error Umum n8n Bot WhatsApp: Troubleshooting Lengkap untuk panduan lengkapnya.
