Troubleshooting

Runbook singkat untuk insiden yang paling sering muncul di docs + aplikasi.

Matrix cepat

Problem	Gejala	Diagnosa awal	Fix cepat
Build docs gagal	docusaurus build merah	broken links/frontmatter/MD syntax	perbaiki file yang disebut stack trace, build ulang
Deploy Pages gagal auth	Unauthorized / Authentication error	token/account id tidak valid di runtime	export CLOUDFLARE_API_TOKEN + CLOUDFLARE_ACCOUNT_ID, deploy ulang
Endpoint protected gagal	401/403 konsisten	mismatch guard/token expired	login ulang, cek middleware route
OTP kena limiter	response limit/rate	throttle key aktif	tunggu window, kurangi retry burst
Integrasi chat gagal	error init firestore/service	dependency credential/config tidak lengkap	verifikasi env + service account lalu restart worker
Data mismatch pasca migration	API gagal di field tertentu	schema drift antar env	rollback terkontrol + jalankan migration yang benar

1) Build docs gagal

Perintah verifikasi:

cd docs-site/docusaurus
npm install
npm run build

Checklist:

• Pastikan tidak ada slug duplikat.
• Pastikan file baru sudah masuk sidebars.js bila perlu.
• Perbaiki link internal yang broken (/docs/...).

2) Deploy Cloudflare Pages gagal (auth/runtime)

Minimum gate sebelum deploy:

test -n "$CLOUDFLARE_API_TOKEN" || { echo "missing token"; exit 1; }
test -n "$CLOUDFLARE_ACCOUNT_ID" || { echo "missing account id"; exit 1; }

Jika masih gagal:

1. Cek project name (example2-docs-customa) tidak typo.
2. Cek token punya izin Pages deploy.
3. Cek account id sesuai akun tempat project berada.

3) API unauthorized terus

Urutan isolasi masalah:

1. Cek route group dan middleware.
2. Cek mode auth endpoint (session vs bearer).
3. Cek role/policy actor.
4. Cek masa berlaku token/session.

4) OTP rejected karena rate limit

Penyebab	Cara bukti	Aksi
Retry terlalu cepat	timestamp request berdekatan	pasang backoff di client
Shared IP throttled	banyak request dari satu IP	per-user key + cooldown

5) Incident data mismatch pasca release

Langkah aman:

1. Freeze write sementara jika impact tinggi.
2. Snapshot bukti (query gagal, stack trace, migration terakhir).
3. Bandingkan schema env target vs source.
4. Putuskan: forward-fix atau rollback.
5. Catat RCA ringkas di changelog internal.

6) Paket verifikasi setelah perbaikan

Verifikasi	Kriteria lulus
Build docs	sukses tanpa error fatal
URL docs utama	HTTP 200
Endpoint kritikal	success sesuai role
Log error	tidak ada burst error baru 15–30 menit