Xử lý sự cố

Tài liệu tra cứu theo triệu chứng, nguyên nhân và cách khắc phục cho các lỗi mà học viên gặp khi chạy lab này, được nhóm theo nơi chúng xuất hiện.

Mọi mục dưới đây đều là một lỗi thật: mười một lỗi được ghi lại trong các file README của từng phần của lab, cộng thêm năm lỗi bắt được trong lúc dựng và kiểm thử workshop này. Hãy tìm triệu chứng của bạn, đọc nguyên nhân, áp dụng cách khắc phục. Nếu không có gì ở đây khớp, các mục ## Common failures của lộ trình instructor bao quát phía người điều phối cho từng module sâu hơn, và Solutions Architect của bạn là điểm dừng tiếp theo.

Bộ công cụ và chuẩn bị

`dbt` lỗi với một lỗi import `mashumaro`, hoặc không cài được

Triệu chứng - việc cài dbt-snowflake hoặc dbt-clickhouse thất bại, hoặc dbt báo một lỗi import có nhắc mashumaro mà nhìn bề ngoài chẳng liên quan gì đến phiên bản Python của bạn.
Nguyên nhân - dbt-snowflake và dbt-clickhouse đều yêu cầu Python 3.11, 3.12 hoặc 3.13. Python 3.14+ làm hỏng phụ thuộc mashumaro mà cả hai dùng chung, và lỗi thường lộ ra ở một module không liên quan, sau khi sai sót đã xảy ra rồi.
Khắc phục - cài 3.13 song song với Python hệ thống của bạn (ví dụ brew install python@3.13) và dựng lại virtualenv với interpreter đó một cách tường minh: python3.13 -m venv .venv.

Môi trường nguồn Snowflake

`terraform init` lỗi với một lỗi provider

Triệu chứng - terraform init trong workshop_public/snowflake_migration_lab/01-setup-snowflake/ thất bại trong lúc phân giải một provider.
Nguyên nhân - binary Terraform quá cũ hoặc không có kết nối mạng tới Terraform registry.
Khắc phục - dùng Terraform >= 1.6 và xác nhận truy cập internet tới registry.

`snowsql` bị từ chối kết nối

Triệu chứng - snowsql -a ${SNOWFLAKE_ORG}-${SNOWFLAKE_ACCOUNT} -u ${SNOWFLAKE_USER} từ chối kết nối.
Nguyên nhân - SNOWFLAKE_ORG hoặc SNOWFLAKE_ACCOUNT bị sai.
Khắc phục - kiểm tra lại cả hai giá trị so với account bạn đã tạo, rồi thử lại đúng lệnh snowsql đó.

`dbt run` lỗi với `relation not found`

Triệu chứng - dbt run trong dự án dbt của Phần 1 báo một relation không tồn tại.
Nguyên nhân - cấu trúc database chưa bao giờ được tạo.
Khắc phục - chạy ./setup.sh --skip-seed trước, và xác nhận profiles.yml trỏ đến NYC_TAXI_DB.

Superset báo `connection refused`

Triệu chứng - UI Superset của Phần 1 từ chối kết nối ngay sau khi docker-compose up.
Nguyên nhân - Superset cần khoảng 60 giây để khởi tạo.
Khắc phục - chờ 60 giây rồi thử lại. Nếu vẫn lỗi, hãy xem docker logs nyc_taxi_superset.

Việc nạp dữ liệu mồi lâu hơn dự kiến

Triệu chứng - bước nạp dữ liệu mồi trong workshop_public/snowflake_migration_lab/01-setup-snowflake/ trông như bị treo.
Nguyên nhân - đây là hành vi bình thường của Snowflake ở quy mô này, không phải bị treo. Lệnh insert TABLE(GENERATOR) sinh ra 50M dòng mất khoảng 10-12 phút, và lệnh UPDATE tiếp theo để nạp cột VARIANT TRIP_METADATA cho cả 50M dòng mất thêm 15-20 phút trên một warehouse SMALL.
Khắc phục - hãy để nó chạy. Không bước nào là tương tác; không có gì để thử lại.

Cấp phát ClickHouse Cloud và di chuyển dữ liệu

Xác thực Terraform lỗi 401 Unauthorized

Triệu chứng - lệnh terraform apply trong workshop_public/snowflake_migration_lab/03-migrate-to-clickhouse/ lỗi 401 Unauthorized.
Nguyên nhân - CLICKHOUSE_TOKEN_KEY hoặc CLICKHOUSE_TOKEN_SECRET bị sai, hoặc key thiếu phạm vi quyền cần thiết.
Khắc phục - sinh lại cặp key từ UI của ClickHouse Cloud ở Settings -> API keys, và bảo đảm nó có phạm vi Admin.

Script di chuyển lỗi giữa lúc chạy

Triệu chứng - scripts/02_migrate_trips.py chết giữa đường trong lúc copy 50M dòng.
Nguyên nhân - các gián đoạn tạm thời của mạng hoặc warehouse trong một lượt truyền dài.
Khắc phục - chạy lại với --resume. Script đặt mốc nước theo max(pickup_at) đã có sẵn trong ClickHouse và bỏ qua các dòng nó đã nạp:
```
python scripts/02_migrate_trips.py --resume
```

Script di chuyển lỗi kết nối

Triệu chứng - script di chuyển không kết nối được tới Snowflake hoặc ClickHouse.
Nguyên nhân - một hoặc nhiều biến môi trường của Snowflake hoặc ClickHouse chưa được đặt trong shell hiện tại.
Khắc phục - kiểm tra chúng, rồi source lại các file state trước khi thử lại:
```
echo $SNOWFLAKE_ORG $SNOWFLAKE_ACCOUNT $SNOWFLAKE_USER $SNOWFLAKE_PASSWORD
echo $CLICKHOUSE_HOST $CLICKHOUSE_PASSWORD
```
Hãy chạy source .env && source .clickhouse_state trước, rồi thử lại.

`dbt run` lỗi với `Connection refused` hoặc `Unknown host`

Triệu chứng - dbt run trên dự án ClickHouse không phân giải hoặc không kết nối được tới một host.
Nguyên nhân - CLICKHOUSE_HOST chưa được đặt trong shell hiện tại.
Khắc phục - chạy source .clickhouse_state từ thư mục module, rồi thử lại dbt run.

`dbt` lỗi với `Could not find profile named 'nyc_taxi_ch'`

Triệu chứng - dbt debug hoặc dbt run trong workshop_public/snowflake_migration_lab/03-migrate-to-clickhouse/dbt/nyc_taxi_dbt_ch lỗi ngay lập tức với thông báo thiếu profile.
Nguyên nhân - profile dbt cho ClickHouse chưa bao giờ được thêm vào ~/.dbt/profiles.yml.
Khắc phục - mở workshop_public/snowflake_migration_lab/03-migrate-to-clickhouse/dbt/nyc_taxi_dbt_ch/profiles.yml.example và trộn khối nyc_taxi_ch: của nó vào file ~/.dbt/profiles.yml hiện có như một profile cấp cao thứ hai. Đừng ghi đè file đó - làm vậy sẽ xóa profile nyc_taxi: từ module 01 và làm hỏng vòng lặp refresh ở Bước 4 của nó. Xem 03 Cấp phát và di chuyển, nơi trình bày đầy đủ bước trộn này.

dbt trên ClickHouse

`analytics.agg_hourly_zone_trips` rỗng sau lượt dbt run

Triệu chứng - sau lượt dbt run của module 04, analytics.agg_hourly_zone_trips không có dòng nào, và mọi chart dashboard dựa trên nó không hiện dữ liệu.
Nguyên nhân - đây là điều dự kiến, không phải một lỗi. Filter incremental của model là WHERE pickup_at >= now() - INTERVAL 2 HOUR, chỉ khớp các dòng do producer chuyến đi chạy trực tiếp ghi vào. Mọi dòng do script di chuyển chuyển sang đều là dữ liệu lịch sử, nên không dòng nào rơi vào cửa sổ 2 giờ đó.
Khắc phục - không có gì để sửa. Số không ở đây là giá trị đúng. Bảng sẽ được nạp dữ liệu khi producer ghi trực tiếp vào ClickHouse sau bước cutover của 05 Benchmark và cutover.

Dashboard và benchmark

Superset báo 403 Forbidden

Triệu chứng - UI Superset trả về 403 Forbidden giữa lúc làm module.
Nguyên nhân - cookie phiên đã hết hạn.
Khắc phục - đăng xuất, đăng nhập lại ở http://localhost:8088, rồi chạy lại bash superset/add_clickhouse_connection.sh.

Benchmark hiện `N/A` cho Q7

Triệu chứng - file CSV output của run_benchmark.sh có N/A thay cho một giá trị tăng tốc ở truy vấn 7.
Nguyên nhân - script benchmark không kết nối được tới ClickHouse.
Khắc phục - xác nhận CLICKHOUSE_HOST đã được đặt (source .clickhouse_state) và service đang chạy, rồi chạy lại benchmark.

Một dashboard Superset đã import không kết nối được tới ClickHouse

Triệu chứng - các dashboard được import vào Superset tải lên được, nhưng các chart của chúng không tới được ClickHouse.
Nguyên nhân - file ZIP export đã commit có host được ẩn thành your-instance.clickhouse.cloud. add_clickhouse_connection.sh vá URI thật vào từ .env trước khi import; một lần import thủ công qua UI của Superset thì không.
Khắc phục - hãy dùng bash superset/add_clickhouse_connection.sh thay cho import thủ công, hoặc sửa kết nối sau đó để dùng CLICKHOUSE_HOST và credential thật của bạn.

Cutover và tính tương đương

Phép kiểm tra tính tương đương thất bại, hoặc cutover trông như làm mất dòng dữ liệu

Triệu chứng - phép kiểm tra tương đương số dòng của module 05 thất bại, hoặc cutover trông như đã làm mất dữ liệu.
Nguyên nhân - lượt bắt kịp --resume đã bị bỏ qua. Producer Snowflake ghi liên tục xuyên suốt các module 01-05, nên lượt di chuyển của module 03 chỉ chụp được phần đầu của dữ liệu; phần đuôi chỉ tồn tại trong Snowflake cho đến khi được bắt kịp. Dừng producer Snowflake sớm (ví dụ ngay sau module 01) sẽ âm thầm phá hủy phần trình diễn cutover của module này, vì khi đó không còn phần đuôi nào để bắt kịp.
Khắc phục - hãy chạy lượt bắt kịp trước khi kiểm tra tính tương đương. Nó chỉ chuyển các dòng trong khoảng trống và mất vài giây đến vài phút, không phải 40-50 phút như ban đầu:
```
python scripts/02_migrate_trips.py --resume
bash scripts/01_verify_migration.sh
```