# Cara Mengatasi Error 9Router: Dashboard, Port, dan Fallback (2026)

- URL: https://komunitech.com/blog/tutorial/cara-mengatasi-error-9router-dashboard-port-dan-fallback-2026/
- Diterbitkan: 2026-10-15
- Diperbarui: 2026-10-15
- Penulis: Priyo Harjiyono
- Penerbit: KomuniTech (https://komunitech.com)

---

**TL;DR:** Error paling sering di 9Router adalah dashboard tidak bisa diakses dari luar VPS (biasanya firewall atau HOSTNAME belum 0.0.0.0), port 20128 bentrok, kredensial provider gratis seperti OpenCode Free ditolak dengan 403 FreeTierError, dan konfigurasi hilang setelah update karena volume data tidak ter-mount. Tiap kasus punya cek spesifik dan langkah perbaikan yang bisa kamu jalankan sendiri lewat terminal, tanpa install ulang dari nol.

💡 KEY TAKEAWAY

- **Cek log dulu, jangan tebak:** docker logs -f 9router hampir selalu menunjukkan akar masalah sebelum kamu mencoba fix apa pun.

- **Dashboard tidak kebuka dari luar** hampir selalu soal firewall port 20128 atau HOSTNAME yang belum diset 0.0.0.0, bukan bug aplikasi.

- **Provider gratis (OpenCode Free) sedang bermasalah di banyak instalasi** sejak pertengahan Oktober 2026 — ini isu di sisi provider, bukan konfigurasi kamu yang salah.

- **Update rutin itu wajib:** banyak bug yang dilaporkan pengguna sudah diperbaiki di versi lebih baru, tapi image Docker kadang telat beberapa hari dari rilis kode.

Kamu baru selesai pasang 9Router di VPS, tapi dashboard-nya ngambek, model yang kamu pilih balas error, atau kredensial yang sudah dihubungkan tiba-tiba ditolak. Wajar — 9Router aktif dikembangkan dan versinya naik hampir tiap minggu, jadi error baru bisa muncul kapan saja. Komunitech merangkum error yang paling sering dilaporkan pengguna di issue tracker resmi 9Router per Oktober 2026, dari dashboard sampai fallback model, lengkap dengan cara mendiagnosis dan memperbaikinya.

## Langkah Pertama: Selalu Cek Log Sebelum Menebak

Sebelum masuk ke kasus spesifik, satu kebiasaan yang menghemat banyak waktu adalah membaca log container terlebih dulu:

docker logs -f 9router
Log ini menunjukkan error asli dari aplikasi (crash, port bentrok, koneksi provider gagal) — jauh lebih akurat daripada menebak dari pesan error generik di CLI coding tool kamu. Kalau kamu install dari VPS mengikuti [panduan install 9Router di VPS dengan Docker](/blog/tutorial/cara-install-9router-di-vps-dengan-docker-panduan-lengkap-2026/), log ini ada di container yang sama.

## Dashboard Tidak Bisa Diakses dari Luar VPS

Ini error paling sering ditanyakan pemula. Setelah container jalan, curl localhost:20128 di dalam VPS berhasil, tapi membuka http://ip-vps:20128 dari browser gagal atau timeout.

Dua penyebab yang hampir selalu jadi biang keladinya:

- **Port 20128 belum dibuka di firewall VPS** — cek dengan ufw status (Ubuntu) atau security group kalau pakai cloud provider seperti AWS/GCP. Buka dengan ufw allow 20128/tcp.

- **HOSTNAME belum diset ke 0.0.0.0** — dokumentasi resmi 9Router ([repositori decolua/9router](https://github.com/decolua/9router)) menyatakan container defaultnya sudah HOSTNAME=0.0.0.0, tapi kalau kamu jalankan dari source bukan image resmi, variabel ini perlu diset manual supaya service listen di semua interface, bukan cuma localhost.

Kalau dua hal itu sudah benar dan dashboard masih tidak terbuka, cek juga apakah reverse proxy (Nginx/Caddy) di depan 9Router sudah mengarah ke port yang benar.

## Port 20128 Sudah Dipakai Proses Lain (EADDRINUSE)

Kalau log menunjukkan error port sudah terpakai, cek proses yang menempati port itu:

sudo lsof -i :20128
Ada dua jalan keluar: matikan proses lama, atau jalankan 9Router di port lain dengan env PORT:

docker run -d --name 9router -p 20200:20200
-v "$HOME/.9router:/app/data" -e DATA_DIR=/app/data
-e PORT=20200 decolua/9router:latest
Ingat ganti base URL di tool yang terhubung (Claude Code, Cursor, Cline, dan lainnya) kalau port berubah dari default 20128. Kalau agent kamu berjalan di OpenClaw, langkah mengganti endpoint-nya ada di [cara connect 9Router ke OpenClaw](/blog/tutorial/cara-connect-9router-ke-openclaw-2026/).

## Konfigurasi dan Provider Hilang Setelah Update

Data 9Router (provider, combo, API key, riwayat pemakaian) disimpan di satu file SQLite: $DATA_DIR/db/data.sqlite. Kalau setelah docker pull lalu container baru dibuat ulang provider-mu hilang, penyebabnya hampir pasti volume tidak ter-mount dengan benar saat update.

Cara update yang aman [sesuai dokumentasi resmi](https://github.com/decolua/9router/blob/master/DOCKER.md):

docker pull decolua/9router:latest
docker stop 9router && docker rm 9router
docker run -d --name 9router -p 20128:20128
-v "$HOME/.9router:/app/data" -e DATA_DIR=/app/data
decolua/9router:latest
Selama path -v "$HOME/.9router:/app/data" sama persis dengan instalasi sebelumnya, data lama otomatis terbaca lagi — karena memang disimpan di host, bukan di dalam container. Pastikan juga DATA_DIR=/app/data ikut disertakan; tanpa ini, app bisa jatuh ke lokasi default dan membaca database kosong.

## Image Docker Terbaru Belum Tersedia di Docker Hub

Terkadang kode 9Router di repositori sudah naik versi (misalnya ke v0.5.99), tapi tag latest di Docker Hub masih tertinggal beberapa versi di belakang — situasi ini pernah dilaporkan beberapa pengguna di [issue tracker resmi 9Router](https://github.com/decolua/9router/issues/4705) pada Oktober 2026, dengan jeda publikasi image sekitar beberapa hari dari rilis kode. Kalau fitur atau fix terbaru yang kamu baca di changelog belum terasa setelah docker pull, cek dulu tag image yang benar-benar ter-publish di [Docker Hub](https://hub.docker.com/r/decolua/9router/tags) sebelum menyimpulkan ada bug di sisi kamu.

## Error 403 FreeTierError Saat Pakai OpenCode Free

Salah satu error yang ramai dilaporkan sejak pertengahan Oktober 2026 adalah permintaan ke provider OpenCode Free (oc/) ditolak dengan pesan 403 FreeTierError: OpenCode's free tier can only be used from within OpenCode. Menurut laporan di [issue #4845](https://github.com/decolua/9router/issues/4845), penyebabnya bukan soal header atau sesi yang salah konfigurasi di sisi pengguna — provider di balik layar sedang memverifikasi dari aplikasi mana permintaan itu benar-benar berasal, dan ini juga dialami pengguna client resmi OpenCode (bukan cuma lewat 9Router).

Karena ini masalah kebijakan di sisi provider, bukan konfigurasi 9Router kamu, yang bisa kamu lakukan sementara: pindah ke provider gratis lain seperti Kiro AI atau Vertex AI ($300 kredit gratis), atau pantau [halaman rilis 9Router](https://github.com/decolua/9router/releases) untuk update terbaru. Coba-coba ganti header atau session ID manual juga tidak membantu: pelapor issue #4845 mencatat belasan pull request dengan pendekatan itu dan menyimpulkan semuanya tidak menembus pemeriksaan provider.

## Rate Limit dan Fallback Tidak Jalan Semestinya

Kalau kamu sudah menyusun combo fallback tapi request tetap gagal padahal model cadangan seharusnya bisa menangani, ada beberapa pola yang perlu kamu tahu:

- **Model dengan context window kecil ditaruh di urutan pertama combo** bisa membuat seluruh rantai berhenti di error 400 "maximum context length" tanpa mencoba model berikutnya yang context window-nya lebih besar — urutkan combo dari context window besar ke kecil untuk menghindari ini.

- **Rate limit (429) dari provider custom OpenAI-compatible kadang muncul ke kamu sebagai 503**, bukan 429 asli — ini bisa bikin bingung saat debug, tapi intinya tetap sama: provider itu sedang membatasi, coba lagi beberapa saat atau pindah ke provider lain di combo.

Untuk dasar menyusun combo yang benar dari awal, baca [tutorial cara atur fallback model AI di 9Router](/blog/tutorial/tutorial-cara-atur-fallback-model-ai-di-9router-2026/).

## Checklist Cepat Sebelum Lapor Bug

| Cek
| Perintah / Langkah

| Lihat error asli
| docker logs -f 9router

| Versi sudah terbaru?
| docker pull decolua/9router:latest lalu restart container

| Port kebentrok?
| sudo lsof -i :20128

| Firewall terbuka?
| ufw status, pastikan 20128 allow

| Volume data benar?
| Pastikan -v "$HOME/.9router:/app/data" identik tiap jalankan ulang

| Masalah provider, bukan 9Router?
| Cek [issue tracker resmi](https://github.com/decolua/9router/issues) dengan kata kunci error-mu

## Kapan Harus Lapor ke GitHub, Bukan Coba-Coba Sendiri

Kalau kamu sudah memastikan versi terbaru, log menunjukkan error yang tidak ada di daftar ini, dan kamu sudah mengecek firewall serta volume data, kemungkinan besar itu bug di aplikasi — bukan kesalahan konfigurasi kamu. Lapor lewat [issue tracker resmi 9Router](https://github.com/decolua/9router/issues) dengan menyertakan versi, log lengkap, dan langkah reproduksi, karena proyek ini aktif menerima laporan bug dan rutin merilis update.

Ada batasan yang perlu kamu tahu: 9Router adalah proyek yang berkembang cepat dengan rilis versi hampir tiap minggu — sebagian error di atas bisa saja sudah diperbaiki di versi setelah Oktober 2026, atau sebaliknya, celah baru bisa muncul di fitur yang baru ditambahkan. Kalau kamu menghubungkan kredensial sensitif (API key berbayar, akun subscription Pro/Max), selalu cek dulu changelog rilis sebelum update ke versi yang baru keluar di hari yang sama. Kalau error yang berulang mulai lebih mahal daripada manfaatnya, opsi gateway cloud bisa dipertimbangkan; perbandingannya ada di [OpenRouter vs 9Router](/blog/riset/openrouter-vs-9router-panduan-memilih-ai-gateway-router-2026/).

## Pertanyaan yang Sering Ditanya

### Kenapa dashboard 9Router di VPS tidak bisa dibuka dari browser?

Paling sering karena port 20128 belum dibuka di firewall VPS (cek dengan ufw status) atau variabel HOSTNAME belum diset ke 0.0.0.0 kalau kamu menjalankan dari source, bukan image Docker resmi.

### Kenapa error 403 FreeTierError muncul di provider OpenCode Free?

Ini bukan masalah konfigurasi di sisi kamu. Sejak pertengahan Oktober 2026, provider OpenCode Free memverifikasi asal permintaan dan menolak yang dianggap bukan berasal dari aplikasi resminya — dialami juga pengguna client OpenCode asli, bukan cuma lewat 9Router.

### Apakah data provider dan combo hilang kalau 9Router di-update?

Tidak, selama kamu memasang ulang container dengan path volume -v "$HOME/.9router:/app/data" yang sama dan env DATA_DIR=/app/data, semua data tersimpan di host dan otomatis kebaca lagi.

### Bagaimana cara ganti port default 20128 kalau sudah dipakai aplikasi lain?

Tambahkan env -e PORT=20128 diganti ke port bebas, misalnya 20200, lalu sesuaikan juga mapping -p 20200:20200 dan base URL di tool coding yang terhubung.

### Kenapa fallback combo tidak jalan meski model cadangan seharusnya bisa menangani?

Dua penyebab umum: model dengan context window kecil diletakkan pertama di combo (bikin seluruh rantai berhenti di error context overflow), atau rate limit 429 dari provider custom yang tampil sebagai 503 sehingga terlihat seperti server down padahal sebenarnya kena limit.

### Kalau error yang kamu alami tidak ada di daftar ini, harus lapor ke mana?

Ke [issue tracker resmi 9Router di GitHub](https://github.com/decolua/9router/issues), sertakan versi yang kamu pakai, log lengkap dari docker logs, dan langkah untuk mereproduksi error-nya.

## Kesimpulan

Sebagian besar error 9Router yang sering dikeluhkan sebenarnya bisa didiagnosis sendiri lewat tiga langkah: baca log container, pastikan versi sudah terbaru, dan cek apakah masalahnya ada di konfigurasi kamu atau di sisi provider eksternal. Kasus seperti dashboard tidak terbuka dari luar VPS dan port bentrok hampir selalu soal firewall dan konfigurasi jaringan, sementara error seperti 403 FreeTierError memang murni di luar kendali konfigurasi kamu. Kalau kamu baru memulai, mulai dari [panduan install 9Router di VPS](/blog/tutorial/cara-install-9router-di-vps-dengan-docker-panduan-lengkap-2026/) sebelum masuk ke pengaturan fallback yang lebih lanjut.

## Referensi

- [decolua/9router — repositori resmi di GitHub](https://github.com/decolua/9router)

- [9Router — dokumentasi Docker resmi](https://github.com/decolua/9router/blob/master/DOCKER.md)

- [9Router — issue tracker resmi](https://github.com/decolua/9router/issues)

- [Issue #4845 — OpenCode Free 403 FreeTierError](https://github.com/decolua/9router/issues/4845)

- [Issue #4705 — Docker image publikasi tertinggal dari versi kode](https://github.com/decolua/9router/issues/4705)

- [Issue #4663 — rate limit 429 tampil sebagai 503](https://github.com/decolua/9router/issues/4663)

- [Issue #4796 — fallback combo gagal di error context overflow](https://github.com/decolua/9router/issues/4796)