Troubleshooting

Selesaikan masalah umum KilatKoding dengan checklist diagnosis yang langsung mengarah ke sumber masalah.

​

Mulai dari dua command ini

Sebelum men-debug lebih jauh, jalankan:

npm run env:check

dan cek:

GET /api/health

Dua pemeriksaan ini biasanya sudah cukup untuk menunjukkan apakah masalah kamu berasal dari env, feature toggle, atau konektivitas database.

​

Masalah umum

Halaman auth atau dashboard tidak bekerja

Periksa NEXT_PUBLIC_SUPABASE_URL dan NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY.

Kalau halaman auth menampilkan notice konfigurasi, biasanya artinya auth memang dimatikan lewat toggle atau public env Supabase belum lengkap.

Setelah mengubah .env atau .env.local, restart npm run dev lalu jalankan lagi npm run env:check.

Kalau auth memang belum mau dipakai, set:

NEXT_PUBLIC_ENABLE_AUTH=false

Billing atau admin selalu menampilkan fallback

Biasanya SUPABASE_SERVICE_ROLE_KEY belum ada. Fitur billing, webhook, avatar signed URL, audit log, admin reporting, dan rate limit persisten membutuhkannya.

Checkout gagal membuat payment

Periksa:

• NEXT_PUBLIC_ENABLE_PAYMENTS
• PAYMENT_PROVIDER
• credential Midtrans atau Doku
• migrasi payments dan subscriptions

Pembayaran sukses di gateway tetapi subscription tidak aktif

Biasanya webhook belum sampai, URL webhook salah, atau signature verification gagal. Periksa route webhook yang sesuai dan pastikan domain production sudah benar.

Form kontak tidak mengirim email

Periksa RESEND_API_KEY, EMAIL_FROM, dan opsional CONTACT_EMAIL. Pastikan domain sender sudah diverifikasi di Resend.

AI route mengembalikan 503 atau 429

503 biasanya berarti provider belum dikonfigurasi. 429 biasanya berarti usage limit atau rate limit tercapai.

Akses admin tidak muncul

Pastikan user kamu ada di user_roles sebagai admin. ADMIN_EMAILS hanya membantu bootstrap awal.

Playwright gagal saat pertama kali dijalankan

Install browser dulu:

npx playwright install chromium

​

Prompt AI yang bisa langsung kamu pakai

Bantu saya mendiagnosis masalah di KilatKoding berikut:

Gejala:
[jelaskan error, endpoint yang gagal, atau behavior yang salah]

Konteks:
- Environment: [local / staging / production]
- Fitur aktif: [jelaskan toggle aktif]
- Payment provider: [midtrans / doku / tidak pakai]
- AI provider: [openai / anthropic / tidak pakai]
- Perubahan terakhir yang saya lakukan: [jelaskan]

Tolong beri saya:
1. 3 sampai 5 hipotesis penyebab paling mungkin
2. Urutan pengecekan tercepat
3. File, env, tabel, atau route yang harus saya cek
4. Cara membedakan root cause utama dari gejala samping
5. Langkah perbaikan yang paling aman

​

Checklist diagnosis cepat

Gejala	Hal pertama yang dicek
Banyak fitur disabled atau fallback	.env, .env.local, restart dev server, lalu npm run env:check
Login redirect aneh	Redirect URL Supabase dan auth callback
Admin kosong	Service role dan role admin
Payment tidak final	Webhook URL dan signature
Avatar gagal	Storage migration dan service role
Contact form gagal	Resend key dan sender domain

​

Kapan harus cek database langsung

Cek database langsung jika masalahnya menyangkut:

• user role,
• status subscription,
• payment record,
• audit trail,
• webhook event log.

Biasanya tabel yang perlu kamu lihat adalah user_roles, subscriptions, payments, audit_logs, dan webhook_events.

​

Kapan harus cek kode

Masuk ke kode jika:

• env sudah benar tetapi perilaku masih salah,
• Kamu baru mengubah file config/*,
• Kamu mengubah route handler atau komponen dashboard,
• Kamu menambah integrasi baru di atas pola yang sudah ada.

Kalau kamu sedang rebrand besar-besaran, masalah yang tampak seperti bug kadang hanya efek dari copy, navigasi, atau env toggle yang belum diselaraskan.