20 Error n8n Paling Sering Terjadi dan Cara Mengatasinya

Error n8n yang paling sering kami temui hampir tidak pernah berasal dari bug aplikasi. Sembilan dari sepuluh kasus berakar pada empat hal: konfigurasi lingkungan yang keliru, izin folder yang salah, sumber daya server yang habis, atau layanan luar yang berubah tanpa pemberitahuan.

Artikel ini menyusun 20 error yang paling sering muncul di instance self-hosted, dikelompokkan menurut area masalahnya, lengkap dengan cara mendiagnosis dan memperbaikinya. Mulailah dari bagian pertama, karena di situlah alat diagnosis dasarnya.

Tiga Perintah yang Menjawab Sebagian Besar Pertanyaan

Sebelum menebak-nebak, jalankan tiga perintah ini. Biasanya jawabannya sudah kelihatan di sini.

# Apakah semua container hidup?
docker compose ps

# Apa yang dikatakan n8n sendiri?
docker compose logs --tail=100 n8n

# Apakah server masih punya ruang?
df -h && free -h

Kolom status pada perintah pertama adalah petunjuk pertama. Container yang berulang kali restart menandakan masalah konfigurasi atau memori, bukan masalah workflow.

Kelompok 1: Instalasi dan Container

Error 1: Container n8n restart terus menerus

Penyebab tersering: izin folder data. Container n8n berjalan sebagai user dengan UID 1000, dan kalau folder data dimiliki root, ia tidak bisa menulis lalu berhenti.

sudo chown -R 1000:1000 ~/n8n-stack/n8n-data
docker compose restart n8n

Penyebab kedua: memori habis. Periksa dengan perintah dmesg untuk melihat apakah sistem mematikan proses karena kehabisan memori. Kalau iya, naikkan RAM atau tambahkan swap.

Error 2: Gagal terhubung ke database saat start

n8n mencoba menghubungi PostgreSQL sebelum database siap menerima koneksi. Ini paling sering terjadi setelah server reboot.

Solusinya bukan menambah jeda, tapi memakai healthcheck. Pasang healthcheck pada service postgres, lalu di service n8n pakai depends_on dengan condition service_healthy. Konfigurasi lengkapnya ada di panduan install n8n di VPS.

Error 3: Port sudah dipakai

Ada layanan lain yang sudah memakai port 80 atau 443, biasanya Nginx atau Apache yang terpasang sebelumnya.

# Cari siapa yang memakai port
sudo lsof -i :80
sudo lsof -i :443

# Matikan web server lama kalau tidak dipakai
sudo systemctl stop nginx
sudo systemctl disable nginx

Error 4: Sertifikat SSL gagal terbit

Tiga penyebab, dan urutan pemeriksaannya penting. Pertama, A record subdomain belum menunjuk ke IP VPS. Kedua, port 80 terblokir sehingga proses verifikasi tidak bisa berjalan. Ketiga, Anda sudah terlalu sering mencoba dan kena batas permintaan dari penerbit sertifikat.

# Pastikan DNS sudah benar
dig +short n8n.domainanda.com

# Pastikan port 80 terbuka
sudo ufw status

Kalau kena batas permintaan, tunggu beberapa jam sebelum mencoba lagi. Mencoba berulang hanya memperpanjang masa tunggu. Latar belakang soal penerbitan sertifikat ada di SSL gratis untuk website.

Kelompok 2: Webhook

Error 5: URL webhook menunjuk ke localhost

Ini error nomor satu di instalasi self-hosted. Anda membuat workflow dengan trigger Webhook, tapi URL yang ditampilkan n8n berisi alamat localhost sehingga layanan luar tidak bisa memanggilnya.

Penyebabnya variabel WEBHOOK_URL yang belum diisi. Tambahkan ke file compose Anda, isi dengan alamat publik lengkap termasuk https, lalu jalankan ulang container.

Error 6: Webhook merespons 404

Dua kemungkinan. Pertama, workflow belum diaktifkan. URL test hanya hidup saat Anda menekan tombol dengar di editor, sedangkan URL produksi baru aktif setelah workflow dinyalakan. Kedua, Anda memakai URL test padahal seharusnya URL produksi. Perhatikan bedanya di panel node Webhook.

Error 7: Webhook timeout dari sisi pemanggil

Layanan luar punya batas waktu tunggu, sering kali hanya beberapa detik. Kalau workflow Anda menjalankan proses panjang sebelum membalas, pemanggil menganggapnya gagal lalu mencoba lagi, dan Anda mendapat eksekusi ganda.

Solusinya: atur node Webhook agar langsung membalas begitu permintaan diterima, lalu lanjutkan proses panjangnya setelah balasan terkirim. Untuk instance yang webhooknya sangat ramai, pertimbangkan proses webhook terpisah seperti dijelaskan di panduan scaling n8n.

Error 8: Webhook menerima data tapi isinya kosong

Biasanya karena pengirim memakai format yang tidak diharapkan, misalnya form data padahal workflow mengharapkan JSON. Aktifkan opsi raw body pada node Webhook untuk melihat isi mentahnya, lalu sesuaikan pemrosesannya.

Kelompok 3: Credential dan Autentikasi

Error 9: Credential tidak bisa didekripsi

Muncul setelah restore dari backup atau setelah memindahkan instance. Penyebabnya satu: encryption key di instance baru berbeda dari yang lama.

Kalau Anda masih menyimpan kunci lama, pasang kembali nilai itu ke variabel N8N_ENCRYPTION_KEY lalu jalankan ulang. Kalau kuncinya benar-benar hilang, tidak ada cara memulihkan credential dan Anda harus membuatnya ulang satu per satu. Ini alasan kenapa kunci tersebut wajib disimpan terpisah, seperti dijelaskan di panduan backup n8n.

Error 10: Token OAuth kedaluwarsa

Workflow yang tadinya jalan tiba-tiba gagal dengan error autentikasi. Beberapa penyedia mencabut refresh token setelah periode tidak aktif atau saat pemilik akun mengubah password.

Perbaikannya adalah menghubungkan ulang credential lewat antarmuka n8n. Untuk mencegah kejutan, pasang Error Workflow yang memberi tahu Anda saat ada kegagalan autentikasi, sehingga ketahuan sebelum pelanggan yang komplain.

Error 11: Callback OAuth gagal

Saat menghubungkan credential OAuth, browser dialihkan ke alamat yang salah. Ini terjadi kalau variabel N8N_HOST atau WEBHOOK_URL tidak sesuai dengan domain yang benar-benar Anda pakai. URL callback harus persis sama dengan yang didaftarkan di aplikasi penyedia, termasuk ada atau tidaknya garis miring di akhir.

Error 12: Kena batas permintaan dari API luar

Layanan yang Anda panggil membatasi jumlah permintaan per satuan waktu. Workflow yang memproses data dalam jumlah besar mudah menabraknya.

Tiga penanganan yang efektif: aktifkan opsi coba lagi pada node dengan jeda yang meningkat, sisipkan node Wait di dalam perulangan, dan pakai Split In Batches supaya permintaan tidak dikirim sekaligus.

Kelompok 4: Eksekusi Workflow

Error 13: Workflow terjadwal jalan di waktu yang salah

Gejala khasnya meleset tujuh jam, dan itu petunjuk langsung: zona waktu server masih UTC sementara Anda berpikir dalam WIB.

- GENERIC_TIMEZONE=Asia/Jakarta
- TZ=Asia/Jakarta

Tambahkan keduanya ke file compose lalu jalankan ulang. Perhatikan bahwa workflow yang sudah dibuat sebelumnya mungkin perlu disimpan ulang agar mengambil zona waktu yang baru.

Error 14: Workflow terjadwal tidak jalan sama sekali

Periksa berurutan: apakah workflow sudah diaktifkan, apakah container n8n benar-benar hidup selama jadwal seharusnya berjalan, dan apakah ada lebih dari satu proses main yang aktif. Kalau instance Anda sempat mati saat jadwal tiba, eksekusi yang terlewat tidak dikejar otomatis.

Error 15: Eksekusi berhenti di tengah tanpa pesan jelas

Hampir selalu kehabisan memori. Workflow menarik data besar, proses Node.js melampaui batas, dan sistem mematikannya.

# Cek apakah proses dimatikan karena memori
dmesg | grep -i "killed process"

# Pantau pemakaian saat workflow berjalan
docker stats

Perbaikan jangka pendek adalah memproses data dalam potongan kecil dengan Split In Batches alih-alih sekaligus. Jangka panjangnya, naikkan RAM server.

Error 16: Eksekusi terduplikasi

Satu pemicu menghasilkan dua eksekusi. Tiga kemungkinan: pemanggil webhook mengulang karena tidak mendapat balasan tepat waktu, ada dua container main aktif pada queue mode, atau workflow dijalankan manual bersamaan dengan jadwal otomatisnya.

Terlepas dari penyebabnya, workflow yang mengirim pesan atau memproses pembayaran wajib punya penjaga anti kirim ganda: simpan penanda setelah berhasil, lalu periksa penanda itu di awal eksekusi berikutnya.

Error 17: Node Code gagal dengan error module tidak ditemukan

Node Code di n8n berjalan di lingkungan terbatas dan tidak semua library Node.js tersedia. Pada instance self-hosted, Anda bisa mengizinkan modul eksternal lewat variabel lingkungan yang menyebutkan nama modul yang diizinkan. Pada n8n Cloud hal ini dibatasi, yang merupakan salah satu alasan orang pindah ke self-hosted seperti dibahas di n8n self-hosted vs cloud.

Kelompok 5: Performa dan Sumber Daya

Error 18: Disk penuh

Ini penyebab paling umum instance yang tadinya mulus tiba-tiba mati setelah berjalan berbulan-bulan. Pelakunya riwayat eksekusi yang tidak pernah dibersihkan.

# Lihat pemakaian disk
df -h

# Lihat apa yang dimakan Docker
docker system df

Perbaikan segera: bersihkan image dan container yang tidak terpakai dengan docker system prune. Perbaikan permanen: aktifkan pruning riwayat eksekusi lewat variabel EXECUTIONS_DATA_PRUNE dan EXECUTIONS_DATA_MAX_AGE.

Error 19: Antarmuka n8n lambat dibuka

Kalau membuka daftar workflow atau daftar eksekusi terasa berat, biasanya tabel eksekusi sudah menumpuk terlalu banyak baris. Aktifkan pruning, dan kalau perlu bersihkan riwayat lama secara manual.

Kalau editor melambat khusus saat ada workflow berat berjalan, itu masalah yang berbeda dan solusinya adalah queue mode, bukan pembersihan data.

Error 20: Instance tidak bisa diakses setelah update

Update yang gagal biasanya karena migrasi database tidak selesai atau ada perubahan yang membutuhkan penyesuaian konfigurasi.

# Lihat apa yang terjadi saat start
docker compose logs --tail=200 n8n

Kalau Anda perlu kembali ke versi sebelumnya, ganti tag image dari latest ke nomor versi yang sebelumnya berjalan lalu jalankan ulang. Ini alasan kenapa backup sebelum update bukan formalitas: migrasi database berjalan satu arah, dan kembali ke versi lama tanpa dump database yang cocok bisa gagal.

Tabel Diagnosis Cepat

Pasang Error Workflow Supaya Tahu Lebih Awal

Sebagian besar kerugian dari error n8n bukan datang dari error itu sendiri, tapi dari lamanya waktu sampai Anda menyadarinya. Workflow yang gagal diam-diam selama tiga hari jauh lebih merugikan daripada workflow yang gagal sekali tapi langsung ketahuan.

n8n punya fitur Error Workflow: workflow khusus yang otomatis dijalankan setiap kali workflow lain gagal. Buat satu workflow sederhana yang menerima data kegagalan lalu mengirimnya ke WhatsApp atau Slack tim Anda, kemudian tetapkan sebagai Error Workflow di pengaturan setiap workflow penting.

Kebiasaan yang Mencegah Sebagian Besar Error Ini

1. Backup sebelum update, selalu. Migrasi database berjalan satu arah dan sulit dibatalkan tanpa dump yang cocok.
2. Aktifkan pruning riwayat sejak hari pertama. Ini mencegah error disk penuh dan antarmuka lambat sekaligus.
3. Simpan encryption key di pengelola password. Satu langkah yang menghemat berhari-hari pekerjaan saat restore.
4. Pasang Error Workflow di semua workflow produksi. Supaya kegagalan ketahuan dalam hitungan menit, bukan hari.
5. Beri ruang memori yang lega. Sebagian besar error eksekusi yang membingungkan sebenarnya adalah masalah memori yang menyamar.
6. Uji workflow dengan data yang tidak rapi. Field kosong, format tanggal aneh, dan karakter khusus adalah penyebab kegagalan yang tidak muncul saat pengujian dengan data ideal.

Pertanyaan Umum (FAQ)

Kesimpulan

Sebagian besar error n8n punya penyebab yang sama berulang kali: WEBHOOK_URL yang belum diisi, encryption key yang tidak sinkron, zona waktu yang masih UTC, izin folder yang salah, dan disk yang penuh karena riwayat eksekusi. Menyelesaikan kelima hal ini di awal instalasi menghapus mayoritas masalah yang akan Anda hadapi setahun ke depan.

Untuk sisanya, kuncinya adalah tahu lebih awal. Pasang Error Workflow di setiap workflow produksi dan pemantauan uptime eksternal untuk instance secara keseluruhan. Kalau Anda ingin sebagian beban pemeliharaan ini ditangani penyedia, n8n Hosting HostingEkspres datang dengan n8n terpasang, backup harian, dan auto update sehingga beberapa penyebab error di atas tidak pernah jadi urusan Anda.