Troubleshooting

Rujukan gejala, penyebab, dan perbaikan untuk setiap kegagalan yang terlihat saat membangun dan menguji workshop ini, dikelompokkan menurut tempat munculnya.

Setiap entri di bawah adalah kegagalan yang benar-benar terjadi saat membangun dan menguji workshop ini. Temukan gejala Anda, baca alasannya, terapkan perbaikannya. Jika tidak ada yang cocok, serahkan masalahnya kepada coding agent Anda - panduan mandiri memuat prompt siap-tempel yang mengubahnya menjadi instruktur Anda.

Windows dan WSL 2

`wsl --install` tidak tersedia atau hanya mencetak bantuan

Gejala - PowerShell Administrator tidak mengenali wsl --install, atau ia mencetak bantuan alih-alih memasang Ubuntu.
Mengapa - Windows berada di bawah minimum workshop, pembaruan yang tertunda belum diterapkan, atau kebijakan korporat menonaktifkan WSL.
Perbaikan - jalankan Windows Update dan pastikan Windows 11 atau Windows 10 versi 2004 (build 19041) atau lebih baru. Restart, lalu ikuti langkah pemasangan WSL manual dari Microsoft. Pada mesin yang dikelola, seorang administrator harus mengizinkan fitur Windows yang diperlukan.

Sebuah perintah "not recognized" di PowerShell

Gejala - PowerShell menolak ./preflight.sh, export, source, atau perintah Bash lain dari workshop.
Mengapa - setup Windows memakai PowerShell hanya untuk bootstrap WSL yang diberi label secara eksplisit. Perintah workshop berjalan di dalam Ubuntu pada WSL 2.
Perbaikan - buka Ubuntu dari menu Start, lalu kembali ke direktori aplikasi dan jalankan preflight di sana:
```
cd ~/ClickHouse_Demos/workshops/build_workshop/app
./preflight.sh
```

Repositori berada di bawah `/mnt/c`

Gejala - bind mount Docker lambat, skrip mengalami kegagalan izin atau akhiran baris, atau jalur repositori dimulai dengan /mnt/c/Users/....
Mengapa - repositori di-clone ke filesystem Windows alih-alih filesystem Linux milik WSL.

Perbaikan - simpan salinan lama hanya jika Anda memerlukan pekerjaan yang belum di-commit. Jika tidak, buka Ubuntu dan clone salinan bersih di direktori home Linux Anda:

cd ~
git config --global core.autocrlf input
git clone https://github.com/ClickHouse/ClickHouse_Demos.git
cd ClickHouse_Demos
git switch build-workshop-v1
cd workshops/build_workshop/app
cp .env.workshop.example .env.workshop

Ubuntu berjalan sebagai WSL 1

Gejala - wsl --list --verbose menampilkan Ubuntu dengan VERSION 1, atau Docker Desktop tidak dapat berintegrasi dengan distro-nya.
Mengapa - distro-nya lebih tua daripada WSL 2 atau dipasang dengan WSL 1 sebagai defaultnya.
Perbaikan - buka PowerShell sebagai Administrator, konversikan, lalu buka kembali Ubuntu:
```
wsl --set-version Ubuntu 2
wsl --set-default-version 2
wsl --list --verbose
```

`docker` tidak tersedia di dalam Ubuntu

Gejala - Docker Desktop berjalan, tetapi Ubuntu menyatakan docker: command not found atau tidak dapat menjangkau daemon-nya.
Mengapa - engine WSL Docker Desktop atau integrasi Ubuntu-nya dinonaktifkan.
Perbaikan - aktifkan Docker Desktop -> Settings -> General -> Use the WSL 2 based engine dan Resources -> WSL Integration -> Ubuntu, terapkan perubahannya, lalu jalankan wsl --shutdown di PowerShell dan buka kembali Ubuntu. docker version kemudian harus menampilkan bagian Client maupun Server.

WSL atau Docker punya memori kurang dari 6 GB

Gejala - preflight melaporkan memori tidak cukup, atau docker info --format 'Docker memory: {{.MemTotal}} bytes' mencetak kurang dari 6442450944 byte.
Mengapa - backend WSL 2 Docker Desktop memakai batas memori mesin virtual WSL.
Perbaikan - tutup Docker Desktop, buka PowerShell, dan buat batas WSL 8 GB:
```
@('[wsl2]', 'memory=8GB', 'processors=4') |
  Set-Content -Encoding ascii "$env:USERPROFILE\.wslconfig"
wsl --shutdown
```
Jalankan Docker Desktop dan buka kembali Ubuntu. Jalankan ulang perintah docker info dan preflight.

Sebuah skrip melaporkan `/usr/bin/env: 'bash\r': No such file or directory`

Gejala - berkas .sh gagal langsung dan error-nya memuat bash\r atau ^M.
Mengapa - akhiran baris CRLF Windows menggantikan akhiran LF yang diwajibkan repositori.
Perbaikan - di Ubuntu, atur kebijakan WSL Git dan pulihkan checkout yang bersih:
```
git config --global core.autocrlf input
git status --short
git add --renormalize .
```
Tinjau git status sebelum membuang atau meng-commit apa pun. Jika checkout itu tidak memuat pekerjaan yang Anda perlukan, clone bersih di bawah ~/ClickHouse_Demos adalah pemulihan paling aman.

OAuth tidak membuka browser Windows

Gejala - login MCP mencetak sebuah URL tetapi tidak ada jendela browser yang terbuka.
Mengapa - coding agent berjalan di dalam WSL dan penerusan browser tidak tersedia atau diblokir kebijakan korporat.
Perbaikan - salin URL login lengkapnya dari Ubuntu dan tempelkan ke browser Windows biasa. Selesaikan otorisasinya di sana, lalu kembali ke terminal Ubuntu.

Docker

Kontainer tersangkut di "Created" dan tidak pernah berjalan

Gejala - docker info menjawab normal, tetapi docker compose ... up membiarkan kontainer di Created dan tidak ada yang pernah menjadi healthy.
Mengapa - engine Docker tersangkut: daemon-nya merespons, tetapi tidak benar-benar dapat menjalankan sebuah kontainer. Terlihat pada OrbStack selama bring-up langsung.
Perbaikan - jalankan ulang engine Docker Anda (Docker Desktop, OrbStack, atau Colima) dan tunggu sampai ia melaporkan Running, lalu jalankan tumpukannya lagi. Dari mana pun di dalam repositori yang di-clone, jalankan cd "$(git rev-parse --show-toplevel)/workshops/build_workshop/app" && ./preflight.sh; skrip itu menangkap masalah ini sebelum Anda menjalankan tumpukan, dengan menjalankan kontainer sekali-pakai sebagai uji coba.

"port is already allocated" saat up

Gejala - docker compose ... up gagal dengan Bind for 0.0.0.0:8080 failed: port is already allocated (atau :8000).
Mengapa - proses lain, atau kontainer workshop lama, sudah memegang port host itu.
Perbaikan - dari mana pun di dalam repositori yang di-clone, jalankan cd "$(git rev-parse --show-toplevel)/workshops/build_workshop/app" && ./preflight.sh. Skrip itu menyebutkan apa yang memegang port-nya dan mencetak override tepat yang harus diatur, mengikuti konvensi base-port + 20000, misalnya set FRONTEND_HOST_PORT=28080 in .env.workshop. Variabel override-nya adalah FRONTEND_HOST_PORT, BACKEND_HOST_PORT, dan untuk overlay observability OTEL_GRPC_HOST_PORT / OTEL_HTTP_HOST_PORT. Atur nilai yang disarankan, jalankan ulang preflight, lalu jalankan tumpukannya. Hanya port host yang berpindah; port di dalam kontainer tidak berubah, jadi ini aman.

Peringatan "platform does not match"

Gejala - Docker mencetak peringatan ketidakcocokan platform (misalnya linux/amd64 vs linux/arm64) saat pull atau up.
Mengapa - sebuah image dibangun untuk arsitektur CPU yang berbeda dari mesin Anda, umum di Apple Silicon.
Perbaikan - tidak berbahaya. Itu peringatan, bukan kegagalan; image-nya berjalan lewat emulasi. Biarkan prosesnya berlanjut.

ClickHouse Cloud

Permintaan pertama setelah idle lambat atau 500 sekali

Gejala - kueri atau pemuatan dashboard pertama setelah layanan idle terasa lambat, atau sebuah permintaan mengembalikan 500 sekali lalu berfungsi.
Mengapa - layanan Cloud melakukan idle-scale ke nol dan butuh sekitar 30 detik untuk bangun; permintaan pertama membayar biaya bangun itu. Back end sudah mengizinkan timeout koneksi pertama yang lebih panjang dan mencoba ulang sekali.
Perbaikan - cukup coba lagi, atau tunggu sekitar 30 detik. Ini bukan sebuah fault. Hal ini juga penting di 07 Uji, gagalkan, dan perbaiki: layanan yang baru bangun membuat timeout fault 03 lebih mudah terpicu.

Kata sandi layanan hilang

Gejala - Anda tidak menyimpan kata sandi pengguna default dan tidak dapat menemukannya.
Mengapa - kata sandi layanan tidak ditampilkan lagi setelah Anda meninggalkan alur pembuatannya.
Perbaikan - buka layanannya, masuk ke Settings-nya dan reset kata sandi pengguna default, lalu perbarui CLICKHOUSE_PASSWORD di .env.workshop. Host-nya selalu tersedia dari modal Connect.

Kata sandi Postgres terkelola hilang

Gejala - Anda tidak menyimpan kata sandi admin postgres sekali-pakai dari clickhousectl cloud postgres create.
Mengapa - kata sandi itu hanya ditampilkan sekali, dan API beta postgres get / list bisa mengembalikan hasil kosong atau FORBIDDEN walaupun instansnya sehat.
Perbaikan - clickhousectl cloud postgres reset-password <service-id>, lalu pakai kata sandi baru di .env.workshop (PGPASSWORD) dan di koneksi ClickPipe.

ClickHouse Cloud tidak dapat dijangkau

Gejala - preflight FAIL pada pemeriksaan konektivitas, atau back end tidak dapat terhubung; the command below gagal.

CLICKHOUSE_HOST=$(sed -n 's/^CLICKHOUSE_HOST=//p' .env.workshop | tail -n 1)
CLICKHOUSE_PORT=$(sed -n 's/^CLICKHOUSE_PORT=//p' .env.workshop | tail -n 1)
curl "https://$CLICKHOUSE_HOST:$CLICKHOUSE_PORT/ping"

Mengapa - wifi, VPN, atau firewall; host yang salah (skema atau port tertempel ke CLICKHOUSE_HOST); ketidakcocokan TLS atau port; atau daftar akses IP Cloud memblokir IP Anda.
Perbaikan - pastikan CLICKHOUSE_HOST adalah hostname murni (tanpa https://, tanpa port), CLICKHOUSE_PORT=8443, dan CLICKHOUSE_SECURE=true; periksa VPN dan firewall; pastikan daftar akses IP layanan mengizinkan alamat Anda. Preflight menyebutkan kegagalan spesifiknya - DNS, refused, timeout, atau TLS handshake.

Klien mencetak `Unknown settings: ... skipping`

Gejala - kuerinya berhasil, tetapi setiap pemanggilan mencetak peringatan unknown-setting.
Mengapa - klien yang terpasang secara lokal lebih baru daripada server Cloud dan mengirim setting yang tidak dikenali rilis server itu.
Perbaikan - ulangi perintah pencocokan klien di Modul 00 Langkah 6. Perintah itu membaca versi server Cloud lewat clickhousectl dan memilih rilis klien major/minor yang bersesuaian. Jangan menyembunyikan semua peringatan klien dengan --no-warnings.

CDC (modul 03)

Pembuatan ClickPipe menyatakan `table realtime_trips exists and is not empty`

Gejala - tidak ada sumber daya ClickPipe, tetapi membuatnya kembali gagal karena default.realtime_trips sudah memuat baris.
Mengapa - menghapus sebuah ClickPipe menghilangkan slot replikasi sumbernya tetapi bisa meninggalkan tabel tujuannya. Pipe baru tidak akan menimpa tabel yang tidak kosong itu.

Perbaikan - simpan baris mentah lama dengan nama backup bertimestamp, lalu buat ulang pipe-nya. Ganti placeholder service-ID sekali; perintah ini juga mempertahankan materialized view lama jika ada:

CH_SERVICE_ID=<clickhouse-service-id>
BACKUP_SUFFIX=$(date -u +%Y%m%d%H%M%S)

if clickhousectl cloud service query --id "$CH_SERVICE_ID" \
  --query "EXISTS TABLE nyc_tlc_data.realtime_trips_to_taxi_trips_mv" | grep -q 1; then
  clickhousectl cloud service query --id "$CH_SERVICE_ID" --query "
    RENAME TABLE nyc_tlc_data.realtime_trips_to_taxi_trips_mv
    TO nyc_tlc_data.realtime_trips_to_taxi_trips_mv_backup_${BACKUP_SUFFIX}
  "
fi

clickhousectl cloud service query --id "$CH_SERVICE_ID" --query "
  RENAME TABLE default.realtime_trips
  TO default.realtime_trips_backup_${BACKUP_SUFFIX}
"

Jalankan ulang Modul 03 Langkah 3 dan tunggu tabel default.realtime_trips yang baru sebelum membuat ulang materialized view kanonis di Langkah 4. Hapus backup bertimestamp itu nanti hanya setelah Anda memastikan datanya sudah tidak diperlukan.

ClickPipe tersangkut di "Provisioning"

Gejala - pipe-nya menampilkan Provisioning untuk sementara waktu setelah Anda membuatnya.
Mengapa - snapshot dan penyalaan infrastruktur umumnya memakan beberapa menit, tetapi bisa memakan lebih dari 10 menit bahkan untuk tabel kecil ini.
Perbaikan - periksa progresnya di konsol atau dengan clickhousectl cloud clickpipe list <clickhouse-service-id> dan clickhousectl cloud clickpipe get <clickhouse-service-id> <clickpipe-id>. Selama beberapa menit pertama, teruslah menunggu selagi state atau nilai updatedAt-nya maju. Jika ia masih Provisioning tanpa pembaruan setelah 10 menit, pastikan log pg-trip-writer masih melakukan insert, periksa ulang host, kredensial, publication, dan pemetaan tabelnya, dan periksa error yang dilaporkan pipe-nya. Jangan membuat pipe kedua atau materialized view selagi yang pertama masih provisioning. Jika pemeriksaan sumbernya lulus dan Cloud tidak melaporkan error yang bisa ditindaklanjuti, simpan keluaran get-nya dan eskalasikan ke instruktur atau dukungan ClickHouse Cloud.

Baris tidak masuk ke ClickHouse

Gejala - pipe-nya Running tetapi jumlah baris tujuan tidak bertambah dan dashboard Ops tidak bergerak.
Mengapa - interval sinkronisasi defaultnya sekitar 60 detik, jadi jeda memang wajar; atau generator-nya tidak melakukan insert; atau publication yang dibaca pipe-nya tidak ada.
Perbaikan - tunggu setidaknya 60 detik. Periksa bahwa log pg-trip-writer menampilkan inserted N trips dan salah satu dari created publication pub_taxi (instans Anda sendiri) atau publication ... already exists (fallback terkelola yang disediakan instruktur). Pastikan state pipe-nya Running. Jika publication-nya tidak ada, pipe-nya tidak punya apa pun untuk dibaca - generator membuatnya saat pertama kali berjalan terhadap instans di mana Anda adalah admin.

Materialized view tidak punya baris

Gejala - realtime_trips terisi, tetapi taxi_trips (yang disuplai materialized view CDC) tetap kosong.
Mengapa - materialized view-nya dibuat sebelum target ClickPipe ada, atau ia tidak membaca target CLI di default.realtime_trips.
Perbaikan - tunggu tabel targetnya, lalu salin perintah materialized-view lengkapnya dari Modul 03, Langkah 4. Verifikasi sumbernya lebih dahulu:
```
clickhousectl cloud service query --id <clickhouse-service-id> --query "
  SELECT database, name, engine
  FROM system.tables
  WHERE name = 'realtime_trips'
"
```
Sebuah materialized view memproses baris yang di-insert setelah ia ada; biarkan penulis perjalanan tetap berjalan setelah pembuatannya.

Slot replikasi terhenti

Gejala - pipe-nya terhenti dan WAL membesar di Postgres sumber.
Mengapa - slot yang terhenti menahan WAL; sebuah resync membuat slot baru.
Perbaikan - pada Postgres terkelola Anda sendiri (satu slot, ruang lega) cukup resync pipe-nya dari konsol. Menghapus sebuah pipe akan menghilangkan slot-nya di sumber. Kolam fallback terkelola milik instruktur adalah urusan sisi instruktur - lihat infra/README.md.

Variabel lingkungan

Sebuah export shell menimpa .env.workshop

Gejala - Anda mengatur sebuah nilai di .env.workshop, tetapi kontainernya memakai nilai lain (sering kali OPENAI_API_KEY yang usang, sebuah LANGFUSE_*, atau CLICKHOUSE_PASSWORD).
Mengapa - docker compose menginterpolasi ${VAR} dari shell Anda lebih dahulu, dan variabel shell yang di-export MENANG atas berkas itu.
Perbaikan - di shell tempat Anda menjalankan compose, unset OPENAI_API_KEY LANGFUSE_PUBLIC_KEY LANGFUSE_SECRET_KEY LANGFUSE_BASE_URL CLICKHOUSE_PASSWORD, lalu jalankan tumpukannya lagi. Preflight memberi peringatan saat mendeteksi hal ini.

Kunci ganda di .env.workshop

Gejala - nilai yang Anda atur di berkas itu diabaikan.
Mengapa - kunci yang sama muncul dua kali; kemunculan terakhir yang menang, sesuai semantik docker compose (preflight membacanya dengan cara yang sama).
Perbaikan - hapus duplikat yang lebih awal sehingga hanya nilai yang dimaksud tersisa.

Chat (modul 08)

POST /api/chat mengembalikan 503 dengan petunjuk setup

Gejala - panel chat menampilkan petunjuk setup dan /api/chat mengembalikan 503; sisa aplikasinya normal.
Mengapa - tidak ada OPENAI_API_KEY yang diatur di back end.
Perbaikan - tambahkan OPENAI_API_KEY ke .env.workshop, lalu docker compose --env-file .env.workshop -f docker-compose.workshop.yml -f docker-compose.otel.yml up -d --build backend. Chat adalah satu-satunya fitur yang memerlukannya.

Tidak dapat membuat kunci OpenAI pertama

Gejala - OpenAI tidak mau menerbitkan kunci API pada akun baru.
Mengapa - akun baru memerlukan verifikasi telepon sekali dan tidak punya kredit gratis.
Perbaikan - selesaikan verifikasi telepon, lalu Settings -> Billing: tambahkan metode pembayaran dan beli kredit prabayar minimum $5. Matikan auto-recharge (secara default menyala saat setup) sehingga Anda tidak pernah ditagih melebihi $5 yang Anda tambahkan.

MCP dan OAuth (modul 00 dan 06)

401 pada endpoint MCP

Gejala - mengakses https://mcp.clickhouse.cloud/mcp (atau /clickstack) mengembalikan 401.
Mengapa - diharapkan sebelum Anda menyelesaikan alur OAuth browser; endpoint-nya terautentikasi.
Perbaikan - tambahkan server ke agent Anda, lalu jalankan alur OAuth-nya dan otorisasi di browser, dengan perintah alat Anda:
- Claude Code - jalankan /mcp, pilih server-nya, dan otorisasi (atau claude mcp login <name>).
- Codex CLI - codex mcp login <name>.
- Cursor - buka panel pengaturan MCP dan klik kontrol authorize/login server-nya.
Pastikan juga tombol Connect with MCP aktif untuk layanan Anda.

Laptop korporat memblokir MCP atau OAuth

Gejala - agent Anda tidak dapat menambahkan server MCP, atau pengalihan OAuth-nya diblokir.
Mengapa - kebijakan laptop yang dikelola memblokir penambahan server MCP atau OAuth keluar.
Perbaikan - mesin pribadi adalah fallback tercepat.

Windsurf tidak dapat terhubung lewat HTTP native

Gejala - Windsurf gagal terhubung ke endpoint MCP, atau OAuth-nya tidak stabil.
Mengapa - Windsurf terhubung melalui mcp-remote ketimbang streamable HTTP native.
Perbaikan - gunakan bentuk perintah mcp-remote: { "command": "npx", "args": ["-y", "mcp-remote", "https://mcp.clickhouse.cloud/mcp"] } (tukar /mcp dengan /clickstack saat merangkai ClickStack MCP di modul 06).