249 Postgres249 Postgres
250</h3>250</h3>
251 251
252Gateway menyimpan statusnya dalam database PostgreSQL:
253
254* **Database**: PostgreSQL itu sendiri, di-host sendiri atau terkelola, pada [versi minimum](/docs/id/claude-apps-gateway#prerequisites) atau lebih baru. Database yang hanya mengimplementasikan protokol Postgres, seperti database SQL terdistribusi, tidak didukung.
255* **Alamat**: `store.postgres_url` menerima satu host. Jika database memiliki beberapa node, gunakan alamat yang berada di depannya, seperti endpoint layanan terkelola Anda, load balancer, atau IP virtual. Atur [periode grace kesiapan](#readiness-grace-period) yang lebih lama dari waktu yang diperlukan failover.
256
252Gateway menyimpan lima tabel data ditambah tabel `_migrations`, semuanya dibuat oleh migrasi waktu boot-nya:257Gateway menyimpan lima tabel data ditambah tabel `_migrations`, semuanya dibuat oleh migrasi waktu boot-nya:
253 258
254| Tabel | Isi | Retensi |259| Tabel | Isi | Retensi |
396| CLI `/login`: `Could not resolve the configured HTTP proxy` | Nama host dalam `HTTPS_PROXY` atau `HTTP_PROXY` tidak diselesaikan dari mesin pengembang, biasanya karena tidak terhubung ke jaringan korporat | Minta pengembang terhubung ke jaringan atau VPN Anda dan coba ulang, atau perbaiki URL proxy |401| CLI `/login`: `Could not resolve the configured HTTP proxy` | Nama host dalam `HTTPS_PROXY` atau `HTTP_PROXY` tidak diselesaikan dari mesin pengembang, biasanya karena tidak terhubung ke jaringan korporat | Minta pengembang terhubung ke jaringan atau VPN Anda dan coba ulang, atau perbaiki URL proxy |
397| CLI `/login`: `Could not resolve gateway host <host>` | Mesin tidak dapat menyelesaikan nama DNS internal gateway, biasanya karena tidak berada di jaringan korporat | Minta pengembang terhubung ke jaringan atau VPN Anda, lalu coba ulang `/login` |402| CLI `/login`: `Could not resolve gateway host <host>` | Mesin tidak dapat menyelesaikan nama DNS internal gateway, biasanya karena tidak berada di jaringan korporat | Minta pengembang terhubung ke jaringan atau VPN Anda, lalu coba ulang `/login` |
398| Boot keluar dengan kesalahan validasi konfigurasi yang menamai `store.postgres_url` | Tidak ada Postgres yang dikonfigurasi; gateway memerlukan Postgres | Atur `store.postgres_url`. Untuk pengembangan lokal, gunakan kontainer sekali pakai: `docker run --rm -p 5432:5432 -e POSTGRES_HOST_AUTH_METHOD=trust postgres`. |403| Boot keluar dengan kesalahan validasi konfigurasi yang menamai `store.postgres_url` | Tidak ada Postgres yang dikonfigurasi; gateway memerlukan Postgres | Atur `store.postgres_url`. Untuk pengembangan lokal, gunakan kontainer sekali pakai: `docker run --rm -p 5432:5432 -e POSTGRES_HOST_AUTH_METHOD=trust postgres`. |
404| Boot keluar: `store.postgres_url in <path> is not a URL the gateway can read`, atau sebelum v2.1.290 hanya `Invalid URL` atau `URI error` | URL tidak dapat diurai, misalnya karena mencantumkan lebih dari satu host atau kata sandinya memiliki `/`, `?`, `#`, atau `%` yang tidak dienkode | Sebutkan [satu host](#postgres), dan pindahkan kata sandi ke [`store.password`](/docs/id/claude-apps-gateway-config#store) |
399| Boot keluar: `requires the native binary` | Berjalan di bawah Node bukan biner asli | Instal Claude Code dengan salah satu [metode instalasi mandiri](/docs/id/setup) |405| Boot keluar: `requires the native binary` | Berjalan di bawah Node bukan biner asli | Instal Claude Code dengan salah satu [metode instalasi mandiri](/docs/id/setup) |
400| Boot keluar dengan kesalahan penemuan OIDC setelah `config.load` | `oidc.issuer` tidak dapat dijangkau, atau rantai TLS tidak dipercaya | Periksa issuer dapat dijangkau dari pod dan melayani `/.well-known/openid-configuration`. Atur `ca_cert_pem` untuk PKI pribadi. Jika pod menjangkau IdP hanya melalui proxy forward, atur [`oidc.use_proxy: true`](/docs/id/claude-apps-gateway-config#idp-requests-through-a-forward-proxy); pada versi sebelum v2.1.227, berikan pod rute langsung ke setiap endpoint IdP sebagai gantinya. Jika pod juga tidak dapat menyelesaikan nama host IdP, atau proxy menolak `CONNECT` ke alamat IP, lihat [Proxy-only egress](/docs/id/claude-apps-gateway-config#proxy-only-egress), yang memerlukan v2.1.277 atau lebih baru. |406| Boot keluar dengan kesalahan penemuan OIDC setelah `config.load` | `oidc.issuer` tidak dapat dijangkau, atau rantai TLS tidak dipercaya | Periksa issuer dapat dijangkau dari pod dan melayani `/.well-known/openid-configuration`. Atur `ca_cert_pem` untuk PKI pribadi. Jika pod menjangkau IdP hanya melalui proxy forward, atur [`oidc.use_proxy: true`](/docs/id/claude-apps-gateway-config#idp-requests-through-a-forward-proxy); pada versi sebelum v2.1.227, berikan pod rute langsung ke setiap endpoint IdP sebagai gantinya. Jika pod juga tidak dapat menyelesaikan nama host IdP, atau proxy menolak `CONNECT` ke alamat IP, lihat [Proxy-only egress](/docs/id/claude-apps-gateway-config#proxy-only-egress), yang memerlukan v2.1.277 atau lebih baru. |
401| Boot keluar dengan kesalahan izin Postgres | Peran database kekurangan hak DDL pada skemanya | Berikan peran `CREATE` pada skema gateway sehingga dapat membuat dan mengubah tabelnya saat boot |407| Boot keluar dengan kesalahan izin Postgres | Peran database kekurangan hak DDL pada skemanya | Berikan peran `CREATE` pada skema gateway sehingga dapat membuat dan mengubah tabelnya saat boot |
402| Log: `could not connect to Postgres at boot, attempt 1 of 3` | Database tidak dapat dijangkau ketika gateway dimulai, misalnya pada instance dingin yang jaringannya masih sedang dimulai | Jika gateway kemudian selesai boot, tidak ada tindakan yang diperlukan. Ketika database tidak dapat dijangkau, gateway mencoba koneksi tiga kali, dua detik terpisah, sebelum keluar. Jika keluar dengan `could not connect to Postgres`, periksa `store.postgres_url` dan jalur jaringan ke database. Jika upaya habis waktu daripada ditolak, naikkan [`store.connect_timeout_seconds`](/docs/id/claude-apps-gateway-config#store) untuk memberikan masing-masing lebih lama. |408| Log: `could not connect to Postgres at boot, attempt 1 of 3` | Database tidak dapat dijangkau ketika gateway dimulai, misalnya pada instance dingin yang jaringannya masih sedang dimulai | Jika gateway kemudian selesai boot, tidak ada tindakan yang diperlukan. Ketika database tidak dapat dijangkau, gateway mencoba koneksi tiga kali, dua detik terpisah, sebelum keluar. Jika keluar dengan `could not connect to Postgres`, periksa `store.postgres_url`, termasuk bahwa URL tersebut menyebutkan satu host, dan jalur jaringan ke database. Jika upaya habis waktu daripada ditolak, naikkan [`store.connect_timeout_seconds`](/docs/id/claude-apps-gateway-config#store) untuk memberikan masing-masing lebih lama. |
403| `/oauth/callback` menampilkan "Sign-in could not be completed" | Domain email ditolak, validasi id\_token gagal, atau `email_verified` secara eksplisit `false`, yang gateway selalu tolak tanpa override | Periksa `allowed_email_domains` dan bahwa IdP mengembalikan klaim `email` yang diverifikasi. Untuk `email_verified: false`, perbaiki verifikasi sisi IdP. Jika IdP Anda memancarkan email di bawah nama klaim berbeda, atur `oidc.email_claim`. |409| `/oauth/callback` menampilkan "Sign-in could not be completed" | Domain email ditolak, validasi id\_token gagal, atau `email_verified` secara eksplisit `false`, yang gateway selalu tolak tanpa override | Periksa `allowed_email_domains` dan bahwa IdP mengembalikan klaim `email` yang diverifikasi. Untuk `email_verified: false`, perbaiki verifikasi sisi IdP. Jika IdP Anda memancarkan email di bawah nama klaim berbeda, atur `oidc.email_claim`. |
404| Log: `token exchange failed request_id=<id>: id_token missing email claim` | IdP tidak menyertakan `email` dalam id\_token secara default. Penolakan ini hanya terjadi ketika `allowed_email_domains` diatur; tanpanya, email yang hilang mencetak sesi tanpa email | Konfigurasikan IdP untuk memancarkan `email` dalam id\_token. Okta: tambahkan `email` ke klaim ID-token server otorisasi khusus. Entra: tambahkan `email` sebagai klaim opsional pada pendaftaran aplikasi. PingFederate: aktifkan Kebijakan OpenID Connect yang memancarkan `email`. Jika IdP melayani `email` dari endpoint userinfo tetapi tidak akan menyertakannya dalam id\_token, seperti server otorisasi org Okta, atur `oidc.userinfo_fallback: true`. |410| Log: `token exchange failed request_id=<id>: id_token missing email claim` | IdP tidak menyertakan `email` dalam id\_token secara default. Penolakan ini hanya terjadi ketika `allowed_email_domains` diatur; tanpanya, email yang hilang mencetak sesi tanpa email | Konfigurasikan IdP untuk memancarkan `email` dalam id\_token. Okta: tambahkan `email` ke klaim ID-token server otorisasi khusus. Entra: tambahkan `email` sebagai klaim opsional pada pendaftaran aplikasi. PingFederate: aktifkan Kebijakan OpenID Connect yang memancarkan `email`. Jika IdP melayani `email` dari endpoint userinfo tetapi tidak akan menyertakannya dalam id\_token, seperti server otorisasi org Okta, atur `oidc.userinfo_fallback: true`. |
405| Log: `refresh failed request_id=<id>: invalid_token (…) (at userinfo_no_id_token, …)`, dan pengembang melihat `Cloud gateway session expired` setiap `session.ttl_hours` | IdP menerima token refresh tetapi tidak mengembalikan id\_token dengannya, jadi gateway menanyakan endpoint userinfo IdP untuk klaim pengguna. IdP menolak token akses yang diperbarui di sana. Gateway menjawab `temporarily_unavailable`, jadi Claude Code menyimpan token refresh tetapi tidak dapat memperbarui sesi. Versi gateway sebelum v2.1.260 mencatat baris yang sama tanpa detail `(at …)`. | Atur [`oidc.scope_on_refresh: true`](/docs/id/claude-apps-gateway-config#oidc), tersedia di gateway v2.1.260 atau lebih baru, sehingga permintaan refresh meminta `openid` lagi. Beberapa IdP, seperti Okta, mengembalikan id\_token pada refresh hanya ketika diminta. Di PingFederate, aktifkan **Return ID Token On Refresh Grant** di bawah **Applications > OAuth > OpenID Connect Policy Management** sebagai gantinya. Kunci tidak mengubah perilaku PingFederate. Untuk IdP lain yang masih menghilangkannya, periksa apakah endpoint userinfo menerima token akses yang dikeluarkan oleh refresh. Sebagai solusi sementara, naikkan [`session.ttl_hours`](/docs/id/claude-apps-gateway-config#session). Lihat [Penyiapan penyedia identitas](#identity-provider-setup) untuk tradeoff deprovisioning. |411| Log: `refresh failed request_id=<id>: invalid_token (…) (at userinfo_no_id_token, …)`, dan pengembang melihat `Cloud gateway session expired` setiap `session.ttl_hours` | IdP menerima token refresh tetapi tidak mengembalikan id\_token dengannya, jadi gateway menanyakan endpoint userinfo IdP untuk klaim pengguna. IdP menolak token akses yang diperbarui di sana. Gateway menjawab `temporarily_unavailable`, jadi Claude Code menyimpan token refresh tetapi tidak dapat memperbarui sesi. Versi gateway sebelum v2.1.260 mencatat baris yang sama tanpa detail `(at …)`. | Atur [`oidc.scope_on_refresh: true`](/docs/id/claude-apps-gateway-config#oidc), tersedia di gateway v2.1.260 atau lebih baru, sehingga permintaan refresh meminta `openid` lagi. Beberapa IdP, seperti Okta, mengembalikan id\_token pada refresh hanya ketika diminta. Di PingFederate, aktifkan **Return ID Token On Refresh Grant** di bawah **Applications > OAuth > OpenID Connect Policy Management** sebagai gantinya. Kunci tidak mengubah perilaku PingFederate. Untuk IdP lain yang masih menghilangkannya, periksa apakah endpoint userinfo menerima token akses yang dikeluarkan oleh refresh. Sebagai solusi sementara, naikkan [`session.ttl_hours`](/docs/id/claude-apps-gateway-config#session). Lihat [Penyiapan penyedia identitas](#identity-provider-setup) untuk tradeoff deprovisioning. |
