> ## Documentation Index
> Fetch the complete documentation index at: https://belajarkoding.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

```bash theme={null}
npm run env:check
```

dan cek:

```text theme={null}
GET /api/health
```

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

## Masalah umum

<AccordionGroup>
  <Accordion title="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:

    ```env theme={null}
    NEXT_PUBLIC_ENABLE_AUTH=false
    ```
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="Checkout gagal membuat payment">
    Periksa:

    * `NEXT_PUBLIC_ENABLE_PAYMENTS`
    * `PAYMENT_PROVIDER`
    * credential Midtrans atau Doku
    * migrasi `payments` dan `subscriptions`
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="Form kontak tidak mengirim email">
    Periksa `RESEND_API_KEY`, `EMAIL_FROM`, dan opsional `CONTACT_EMAIL`. Pastikan domain sender sudah diverifikasi di Resend.
  </Accordion>

  <Accordion title="AI route mengembalikan 503 atau 429">
    `503` biasanya berarti provider belum dikonfigurasi. `429` biasanya berarti usage limit atau rate limit tercapai.
  </Accordion>

  <Accordion title="Akses admin tidak muncul">
    Pastikan user kamu ada di `user_roles` sebagai `admin`. `ADMIN_EMAILS` hanya membantu bootstrap awal.
  </Accordion>

  <Accordion title="Playwright gagal saat pertama kali dijalankan">
    Install browser dulu:

    ```bash theme={null}
    npx playwright install chromium
    ```
  </Accordion>
</AccordionGroup>

## Prompt AI yang bisa langsung kamu pakai

```text theme={null}
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.

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