Troubleshooting

Rujukan gejala, penyebab, dan perbaikan untuk kegagalan yang dialami learner saat menjalankan lab ini, dikelompokkan menurut tempat kegagalan itu muncul.

Setiap entri di bawah adalah kegagalan nyata: sebelas yang terdokumentasi di README bagian lab itu sendiri, ditambah lima yang tertangkap saat membangun dan menguji workshop ini. Temukan gejala Anda, baca penyebabnya, terapkan perbaikannya. Jika tidak ada yang cocok di sini, bagian ## Common failures di jalur instructor membahas sisi fasilitator dari setiap modul lebih dalam, dan Solutions Architect Anda adalah pemberhentian berikutnya.

Toolchain dan setup

`dbt` gagal dengan error import `mashumaro`, atau tidak mau terpasang

Gejala - pemasangan dbt-snowflake atau dbt-clickhouse gagal, atau dbt memunculkan error import yang menyebut mashumaro yang tampak tidak berkaitan dengan versi Python Anda.
Penyebab - dbt-snowflake dan dbt-clickhouse keduanya membutuhkan Python 3.11, 3.12, atau 3.13. Python 3.14+ merusak dependensi mashumaro yang mereka bagi bersama, dan kegagalannya biasanya muncul di modul yang tak berkaitan setelah kesalahannya sudah terjadi.
Perbaikan - pasang 3.13 di samping Python sistem Anda (misalnya brew install python@3.13) dan bangun ulang virtualenv dengan interpreter itu secara eksplisit: python3.13 -m venv .venv.

Lingkungan sumber Snowflake

`terraform init` gagal dengan error provider

Gejala - terraform init di workshop_public/snowflake_migration_lab/01-setup-snowflake/ gagal saat me-resolve sebuah provider.
Penyebab - binari Terraform yang lama atau tidak ada akses jaringan ke registry Terraform.
Perbaikan - gunakan Terraform >= 1.6 dan pastikan ada akses internet ke registry.

`snowsql` connection refused

Gejala - snowsql -a ${SNOWFLAKE_ORG}-${SNOWFLAKE_ACCOUNT} -u ${SNOWFLAKE_USER} menolak koneksi.
Penyebab - SNOWFLAKE_ORG atau SNOWFLAKE_ACCOUNT salah.
Perbaikan - periksa ulang kedua nilai terhadap akun yang Anda buat, lalu jalankan kembali perintah snowsql yang sama.

`dbt run` gagal dengan `relation not found`

Gejala - dbt run di proyek dbt Bagian 1 melaporkan sebuah relation yang tidak ada.
Penyebab - struktur database tidak pernah dibuat.
Perbaikan - jalankan ./setup.sh --skip-seed lebih dulu, dan pastikan profiles.yml menunjuk ke NYC_TAXI_DB.

Superset menampilkan `connection refused`

Gejala - UI Superset Bagian 1 menolak koneksi tepat setelah docker-compose up.
Penyebab - Superset butuh sekitar 60 detik untuk inisialisasi.
Perbaikan - tunggu 60 detik dan coba lagi. Jika masih gagal, periksa docker logs nyc_taxi_superset.

Seeding data memakan waktu lebih lama dari perkiraan

Gejala - langkah seed di workshop_public/snowflake_migration_lab/01-setup-snowflake/ tampak macet.
Penyebab - ini perilaku normal Snowflake pada skala ini, bukan hang. INSERT TABLE(GENERATOR) yang menghasilkan 50 juta baris memakan kurang lebih 10-12 menit, dan UPDATE lanjutan yang mengisi kolom VARIANT TRIP_METADATA pada seluruh 50 juta baris memakan 15-20 menit lagi pada warehouse SMALL.
Perbaikan - biarkan berjalan. Tidak ada langkah yang interaktif; tidak ada yang perlu dicoba ulang.

Provisioning ClickHouse Cloud dan migrasi data

Autentikasi Terraform gagal dengan 401 Unauthorized

Gejala - Terraform apply di workshop_public/snowflake_migration_lab/03-migrate-to-clickhouse/ gagal dengan 401 Unauthorized.
Penyebab - CLICKHOUSE_TOKEN_KEY atau CLICKHOUSE_TOKEN_SECRET salah, atau key-nya tidak punya scope yang diperlukan.
Perbaikan - buat ulang pasangan key dari UI ClickHouse Cloud di bawah Settings -> API keys, dan pastikan key itu punya scope Admin.

Skrip migrasi gagal di tengah eksekusi

Gejala - scripts/02_migrate_trips.py mati di tengah penyalinan 50 juta baris.
Penyebab - gangguan sesaat pada jaringan atau warehouse selama transfer yang berjalan lama.
Perbaikan - jalankan ulang dengan --resume. Skrip memakai watermark pada max(pickup_at) yang sudah ada di ClickHouse dan melewati baris yang sudah dimuatnya:
```
python scripts/02_migrate_trips.py --resume
```

Error koneksi skrip migrasi

Gejala - skrip migrasi tidak bisa menjangkau Snowflake atau ClickHouse.
Penyebab - satu atau lebih variabel environment Snowflake atau ClickHouse belum diset di shell saat ini.
Perbaikan - periksa variabelnya, lalu source ulang file state sebelum mencoba lagi:
```
echo $SNOWFLAKE_ORG $SNOWFLAKE_ACCOUNT $SNOWFLAKE_USER $SNOWFLAKE_PASSWORD
echo $CLICKHOUSE_HOST $CLICKHOUSE_PASSWORD
```
Jalankan source .env && source .clickhouse_state lebih dulu, lalu coba lagi.

`dbt run` gagal dengan `Connection refused` atau `Unknown host`

Gejala - dbt run terhadap proyek ClickHouse gagal me-resolve atau tersambung ke sebuah host.
Penyebab - CLICKHOUSE_HOST belum diset di shell saat ini.
Perbaikan - jalankan source .clickhouse_state dari direktori modul, lalu coba lagi dbt run.

`dbt` gagal dengan `Could not find profile named 'nyc_taxi_ch'`

Gejala - dbt debug atau dbt run di workshop_public/snowflake_migration_lab/03-migrate-to-clickhouse/dbt/nyc_taxi_dbt_ch langsung gagal dengan error profil yang hilang.
Penyebab - profil dbt ClickHouse tidak pernah ditambahkan ke ~/.dbt/profiles.yml.
Perbaikan - buka workshop_public/snowflake_migration_lab/03-migrate-to-clickhouse/dbt/nyc_taxi_dbt_ch/profiles.yml.example dan gabungkan blok nyc_taxi_ch:-nya ke dalam ~/.dbt/profiles.yml yang sudah ada sebagai profil tingkat atas kedua. Jangan timpa file itu - melakukannya menghapus profil nyc_taxi: dari modul 01 dan merusak loop refresh di Langkah 4-nya. Lihat 03 Provisioning dan migrasi, yang membahas langkah penggabungan ini secara lengkap.

dbt di ClickHouse

`analytics.agg_hourly_zone_trips` kosong setelah eksekusi dbt

Gejala - setelah dbt run modul 04, analytics.agg_hourly_zone_trips punya nol baris, dan setiap chart dashboard yang ditopangnya tidak menampilkan data.
Penyebab - ini memang diharapkan, bukan kegagalan. Filter inkremental model ini adalah WHERE pickup_at >= now() - INTERVAL 2 HOUR, yang hanya cocok dengan baris yang ditulis producer perjalanan live. Semua baris yang dipindahkan skrip migrasi bersifat historis, jadi tak satu pun masuk ke dalam jendela 2 jam itu.
Perbaikan - tidak ada yang perlu diperbaiki. Nol adalah nilai yang benar di sini. Tabel ini terisi begitu producer menulis langsung ke ClickHouse setelah langkah cutover di 05 Benchmark dan cutover.

Dashboard dan benchmark

Superset menampilkan 403 Forbidden

Gejala - UI Superset mengembalikan 403 Forbidden di tengah modul.
Penyebab - cookie sesi kedaluwarsa.
Perbaikan - log out, log in kembali di http://localhost:8088, lalu jalankan ulang bash superset/add_clickhouse_connection.sh.

Benchmark menampilkan `N/A` untuk Q7

Gejala - CSV keluaran run_benchmark.sh berisi N/A di tempat nilai percepatan untuk query 7.
Penyebab - skrip benchmark tidak bisa tersambung ke ClickHouse.
Perbaikan - pastikan CLICKHOUSE_HOST sudah diset (source .clickhouse_state) dan layanannya berjalan, lalu jalankan ulang benchmark-nya.

Dashboard Superset yang diimpor tidak mau tersambung ke ClickHouse

Gejala - dashboard yang diimpor ke Superset termuat, tetapi chart-nya tidak bisa menjangkau ClickHouse.
Penyebab - ZIP ekspor yang di-commit punya host yang disamarkan menjadi your-instance.clickhouse.cloud. add_clickhouse_connection.sh menambal URI yang sebenarnya dari .env sebelum mengimpor; impor manual melalui UI Superset tidak.
Perbaikan - gunakan bash superset/add_clickhouse_connection.sh alih-alih impor manual, atau sunting koneksinya sesudahnya agar memakai CLICKHOUSE_HOST dan kredensial Anda yang sebenarnya.

Cutover dan paritas

Pemeriksaan paritas gagal, atau cutover tampak kehilangan baris

Gejala - pemeriksaan paritas jumlah baris di modul 05 gagal, atau cutover terlihat seperti kehilangan data.
Penyebab - tahap penyusulan --resume dilewati. Producer Snowflake menulis terus-menerus sepanjang modul 01-05, jadi migrasi modul 03 hanya menangkap awalan dari datanya; ekornya hanya ada di Snowflake sampai disusul. Menghentikan producer Snowflake terlalu awal (misalnya, tepat setelah modul 01) secara senyap memusnahkan demonstrasi cutover modul ini, karena kemudian tidak ada ekor yang tersisa untuk disusul.
Perbaikan - jalankan tahap penyusulan sebelum memeriksa paritas. Tahap itu hanya memindahkan baris jeda dan memakan hitungan detik sampai menit, bukan 40-50 menit seperti aslinya:
```
python scripts/02_migrate_trips.py --resume
bash scripts/01_verify_migration.sh
```