Xử lý sự cố

Tài liệu tham chiếu triệu chứng, nguyên nhân, và cách sửa cho mọi lỗi đã gặp khi xây dựng và kiểm thử workshop này, được nhóm theo nơi nó xuất hiện.

Mọi mục dưới đây đều là một lỗi đã thực sự xảy ra khi xây dựng và kiểm thử workshop này. Hãy tìm triệu chứng của bạn, đọc phần vì sao, rồi áp dụng cách sửa. Nếu không có mục nào khớp, hãy trao vấn đề cho coding agent của bạn - hướng dẫn tự học có một prompt sẵn sàng để dán, biến nó thành giảng viên của bạn.

Windows và WSL 2

`wsl --install` không khả dụng hoặc chỉ in ra phần trợ giúp

Triệu chứng - PowerShell quyền Administrator không nhận wsl --install, hoặc nó in ra phần trợ giúp thay vì cài Ubuntu.
Vì sao - Windows thấp hơn mức tối thiểu của workshop, các bản cập nhật đang chờ chưa được áp dụng, hoặc chính sách công ty vô hiệu hóa WSL.
Cách sửa - hãy chạy Windows Update và xác nhận Windows 11 hoặc Windows 10 phiên bản 2004 (build 19041) trở lên. Khởi động lại, rồi làm theo các bước cài WSL thủ công của Microsoft. Trên máy được quản lý, một người quản trị phải cho phép các tính năng Windows cần thiết.

Một câu lệnh bị báo "not recognized" trong PowerShell

Triệu chứng - PowerShell từ chối ./preflight.sh, export, source, hoặc một câu lệnh Bash khác của workshop.
Vì sao - phần thiết lập Windows chỉ dùng PowerShell cho phần bootstrap WSL được ghi nhãn rõ ràng. Các câu lệnh của workshop chạy bên trong Ubuntu trên WSL 2.
Cách sửa - hãy mở Ubuntu từ menu Start, rồi trở về thư mục ứng dụng và chạy preflight ở đó:
```
cd ~/ClickHouse_Demos/workshops/build_workshop/app
./preflight.sh
```

Repository nằm dưới `/mnt/c`

Triệu chứng - các bind mount của Docker chậm, các script gặp lỗi về quyền hoặc ký tự kết thúc dòng, hoặc đường dẫn repository bắt đầu bằng /mnt/c/Users/....
Vì sao - repository đã được clone vào filesystem của Windows thay vì filesystem Linux của WSL.

Cách sửa - chỉ giữ bản cũ nếu bạn cần phần việc chưa commit. Nếu không, hãy mở Ubuntu và clone một bản sạch trong thư mục home Linux của bạn:

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 đang chạy dưới dạng WSL 1

Triệu chứng - wsl --list --verbose hiển thị Ubuntu với VERSION 1, hoặc Docker Desktop không tích hợp được với distro.
Vì sao - distro có từ trước WSL 2 hoặc được cài với WSL 1 làm mặc định.
Cách sửa - hãy mở PowerShell với quyền Administrator, chuyển đổi nó, rồi mở lại Ubuntu:
```
wsl --set-version Ubuntu 2
wsl --set-default-version 2
wsl --list --verbose
```

`docker` không khả dụng bên trong Ubuntu

Triệu chứng - Docker Desktop đang chạy, nhưng Ubuntu báo docker: command not found hoặc không kết nối được tới daemon.
Vì sao - engine WSL của Docker Desktop hoặc phần tích hợp Ubuntu đang bị tắt.
Cách sửa - hãy bật Docker Desktop -> Settings -> General -> Use the WSL 2 based engine và Resources -> WSL Integration -> Ubuntu, áp dụng thay đổi, rồi chạy wsl --shutdown trong PowerShell và mở lại Ubuntu. Sau đó docker version phải hiển thị cả phần Client lẫn Server.

WSL hoặc Docker có ít hơn 6 GB bộ nhớ

Triệu chứng - preflight báo bộ nhớ không đủ, hoặc docker info --format 'Docker memory: {{.MemTotal}} bytes' in ra ít hơn 6442450944 byte.
Vì sao - backend WSL 2 của Docker Desktop dùng giới hạn bộ nhớ của máy ảo WSL.
Cách sửa - hãy đóng Docker Desktop, mở PowerShell, và tạo một giới hạn WSL 8 GB:
```
@('[wsl2]', 'memory=8GB', 'processors=4') |
  Set-Content -Encoding ascii "$env:USERPROFILE\.wslconfig"
wsl --shutdown
```
Hãy khởi động Docker Desktop và mở lại Ubuntu. Chạy lại câu lệnh docker info cùng preflight.

Một script báo `/usr/bin/env: 'bash\r': No such file or directory`

Triệu chứng - một file .sh lỗi ngay lập tức và thông báo lỗi chứa bash\r hoặc ^M.
Vì sao - ký tự kết thúc dòng CRLF của Windows đã thay thế ký tự LF mà repository yêu cầu.
Cách sửa - trong Ubuntu, hãy đặt chính sách WSL cho Git và phục hồi một bản checkout sạch:
```
git config --global core.autocrlf input
git status --short
git add --renormalize .
```
Hãy xem lại git status trước khi loại bỏ hay commit bất cứ thứ gì. Nếu bản checkout không có phần việc nào bạn cần, một bản clone sạch dưới ~/ClickHouse_Demos là cách khôi phục an toàn nhất.

OAuth không mở browser trên Windows

Triệu chứng - một lần login MCP in ra một URL nhưng không cửa sổ browser nào mở ra.
Vì sao - coding agent đang chạy bên trong WSL và việc chuyển tiếp browser không khả dụng hoặc bị chính sách công ty chặn.
Cách sửa - hãy copy toàn bộ URL login từ Ubuntu và dán nó vào browser Windows thông thường. Hoàn tất việc cấp quyền ở đó, rồi trở về terminal Ubuntu.

Docker

Container đứng ở trạng thái "Created" và không bao giờ khởi động

Triệu chứng - docker info trả lời bình thường, nhưng docker compose ... up để các container ở Created và không có gì trở nên healthy.
Vì sao - Docker engine bị kẹt: daemon vẫn phản hồi, nhưng nó không thực sự khởi động được một container. Đã gặp với OrbStack trong một lần khởi động trực tiếp.
Cách sửa - hãy khởi động lại Docker engine của bạn (Docker Desktop, OrbStack, hoặc Colima) và chờ tới khi nó báo Running, rồi khởi động lại stack. Từ bất cứ đâu bên trong repository đã clone, hãy chạy cd "$(git rev-parse --show-toplevel)/workshops/build_workshop/app" && ./preflight.sh; nó bắt được lỗi này trước khi bạn khởi động stack bằng cách chạy một container dùng một lần để kiểm tra.

"port is already allocated" khi up

Triệu chứng - docker compose ... up lỗi với Bind for 0.0.0.0:8080 failed: port is already allocated (hoặc :8000).
Vì sao - một tiến trình khác, hoặc một container workshop cũ, đang giữ port đó của host.
Cách sửa - từ bất cứ đâu bên trong repository đã clone, hãy chạy cd "$(git rev-parse --show-toplevel)/workshops/build_workshop/app" && ./preflight.sh. Nó nêu tên thứ đang giữ port và in ra chính xác giá trị override cần đặt, theo quy ước base-port + 20000, ví dụ set FRONTEND_HOST_PORT=28080 in .env.workshop. Các biến override là FRONTEND_HOST_PORT, BACKEND_HOST_PORT, và với overlay quan sát là OTEL_GRPC_HOST_PORT / OTEL_HTTP_HOST_PORT. Hãy đặt giá trị được đề xuất, chạy lại preflight, rồi khởi động stack. Chỉ các port của host thay đổi; các port bên trong container không đổi, nên việc này an toàn.

Cảnh báo "platform does not match"

Triệu chứng - Docker in ra một cảnh báo lệch platform (ví dụ linux/amd64 so với linux/arm64) khi pull hoặc up.
Vì sao - một image được build cho kiến trúc CPU khác với máy của bạn, chuyện thường gặp trên Apple Silicon.
Cách sửa - vô hại. Đó là cảnh báo, không phải lỗi; image chạy dưới cơ chế giả lập. Hãy để nó tiếp tục.

ClickHouse Cloud

Request đầu tiên sau khi idle bị chậm hoặc 500 một lần

Triệu chứng - truy vấn hoặc lần tải dashboard đầu tiên sau khi service đã idle thì chậm, hoặc một request bị 500 một lần rồi sau đó hoạt động bình thường.
Vì sao - một service Cloud idle-scale về không và cần khoảng 30 giây để thức; request đầu tiên phải trả cái giá thức đó. Back end đã cho phép timeout kết nối lần đầu dài hơn và retry một lần.
Cách sửa - cứ thử lại, hoặc chờ khoảng 30 giây. Đây không phải lỗi. Điều này cũng quan trọng ở 07 Kiểm thử, lỗi, và sửa: một service đang thức làm timeout của lỗi 03 kích hoạt dễ hơn.

Mất password của service

Triệu chứng - bạn không lưu password của user default và không tìm lại được nó.
Vì sao - password của service không được hiển thị lại sau khi bạn rời luồng tạo service.
Cách sửa - hãy mở service, vào phần Settings của nó và reset password của user default, rồi cập nhật CLICKHOUSE_PASSWORD trong .env.workshop. Host luôn có sẵn từ modal Connect.

Mất password của Postgres được quản lý

Triệu chứng - bạn không lưu password admin postgres dùng một lần từ clickhousectl cloud postgres create.
Vì sao - nó chỉ được hiển thị một lần, và các API postgres get / list ở bản beta có thể trả về rỗng hoặc FORBIDDEN dù instance vẫn khỏe mạnh.
Cách sửa - clickhousectl cloud postgres reset-password <service-id>, rồi dùng password mới trong .env.workshop (PGPASSWORD) và trong kết nối của ClickPipe.

Không kết nối được tới ClickHouse Cloud

Triệu chứng - preflight FAIL ở phép kiểm tra kết nối, hoặc back end không kết nối được; the command below thất bại.

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"

Vì sao - wifi, VPN, hoặc firewall; host sai (một scheme hoặc port bị dán vào CLICKHOUSE_HOST); lệch TLS hoặc port; hoặc một IP-access-list của Cloud đang chặn IP của bạn.
Cách sửa - hãy xác nhận CLICKHOUSE_HOST là hostname trần (không https://, không port), CLICKHOUSE_PORT=8443, và CLICKHOUSE_SECURE=true; kiểm tra VPN và firewall; xác nhận IP access list của service cho phép địa chỉ của bạn. Preflight nêu tên lỗi cụ thể - DNS, bị từ chối, timeout, hoặc TLS handshake.

Client in ra `Unknown settings: ... skipping`

Triệu chứng - các truy vấn thành công, nhưng mỗi lần gọi đều in ra một cảnh báo unknown-setting.
Vì sao - client cài ở local mới hơn server Cloud và gửi một setting mà bản phát hành server đó không nhận ra.
Cách sửa - hãy lặp lại các câu lệnh khớp client ở Module 00 Bước 6. Chúng đọc phiên bản server Cloud qua clickhousectl và chọn bản phát hành client major/minor tương ứng. Đừng ẩn hết cảnh báo của client bằng --no-warnings.

CDC (module 03)

Việc tạo ClickPipe báo `table realtime_trips exists and is not empty`

Triệu chứng - không có tài nguyên ClickPipe nào tồn tại, nhưng việc tạo lại nó thất bại vì default.realtime_trips đã chứa dữ liệu.
Vì sao - việc xóa một ClickPipe loại bỏ replication slot ở nguồn của nó nhưng có thể để lại bảng đích. Một pipe mới sẽ không ghi đè bảng không rỗng đó.

Cách sửa - hãy giữ lại các dòng dữ liệu thô cũ dưới các tên backup có timestamp, rồi tạo lại pipe. Chỉ cần thay placeholder service-ID một lần; các câu lệnh này cũng giữ lại materialized view cũ khi nó tồn tại:

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}
"

Hãy chạy lại Module 03 Bước 3 và chờ bảng default.realtime_trips mới trước khi tạo lại materialized view chuẩn ở Bước 4. Chỉ xóa các bản backup có timestamp về sau khi bạn đã chắc chắn không còn cần dữ liệu của chúng.

ClickPipe kẹt ở "Provisioning"

Triệu chứng - pipe hiển thị Provisioning một lúc sau khi bạn tạo nó.
Vì sao - việc snapshot và khởi động hạ tầng thường mất vài phút, nhưng có thể mất hơn 10 phút dù bảng này nhỏ.
Cách sửa - hãy kiểm tra tiến độ trong console hoặc bằng cả clickhousectl cloud clickpipe list <clickhouse-service-id> và clickhousectl cloud clickpipe get <clickhouse-service-id> <clickpipe-id>. Trong vài phút đầu, hãy tiếp tục chờ trong khi trạng thái hoặc giá trị updatedAt của nó tiến lên. Nếu nó vẫn ở Provisioning mà không cập nhật gì sau 10 phút, hãy xác nhận log của pg-trip-writer vẫn đang insert, kiểm tra lại host, thông tin đăng nhập, publication, và table mapping, rồi xem lỗi mà pipe báo. Đừng tạo pipe thứ hai hay materialized view khi pipe đầu tiên còn đang provisioning. Nếu các phép kiểm tra ở nguồn đều đạt và Cloud không báo lỗi nào có thể xử lý, hãy lưu output của get và chuyển tiếp cho giảng viên hoặc bộ phận hỗ trợ của ClickHouse Cloud.

Dữ liệu không đến ClickHouse

Triệu chứng - pipe đang Running nhưng số dòng ở đích không tăng và dashboard Ops không nhúc nhích.
Vì sao - khoảng sync mặc định là khoảng 60 giây, nên hãy chờ đợi có độ trễ; hoặc bộ sinh dữ liệu không insert; hoặc publication mà pipe đọc không tồn tại.
Cách sửa - hãy chờ ít nhất 60 giây. Hãy kiểm tra log của pg-trip-writer có hiển thị inserted N trips và một trong hai dòng created publication pub_taxi (instance của riêng bạn) hoặc publication ... already exists (một phương án dự phòng được quản lý do giảng viên cung cấp). Hãy xác nhận trạng thái pipe là Running. Nếu publication không có, pipe chẳng có gì để đọc - bộ sinh dữ liệu tạo nó ở lần chạy đầu trên một instance mà bạn có quyền admin.

Materialized view không có dòng nào

Triệu chứng - realtime_trips được lấp đầy, nhưng taxi_trips (do materialized view CDC nạp) vẫn rỗng.
Vì sao - materialized view được tạo trước khi đích của ClickPipe tồn tại, hoặc nó không đọc đích do CLI tạo tại default.realtime_trips.
Cách sửa - hãy chờ bảng đích, rồi copy toàn bộ câu lệnh materialized-view từ Module 03, Bước 4. Hãy kiểm chứng nguồn trước:
```
clickhousectl cloud service query --id <clickhouse-service-id> --query "
  SELECT database, name, engine
  FROM system.tables
  WHERE name = 'realtime_trips'
"
```
Một materialized view xử lý các dòng được insert sau khi nó tồn tại; hãy giữ bộ ghi chuyến xe chạy tiếp sau khi tạo nó.

Replication slot bị đình trệ

Triệu chứng - pipe đình trệ và WAL phình lên trên Postgres nguồn.
Vì sao - một slot bị đình trệ sẽ giữ lại WAL; một lần resync sẽ tạo một slot mới.
Cách sửa - trên Postgres được quản lý của riêng bạn (một slot, dư dả dung lượng), chỉ cần resync pipe từ console. Việc xóa một pipe sẽ loại bỏ slot của nó ở nguồn. Mọi pool dự phòng được quản lý do giảng viên cung cấp là chuyện thuộc phía giảng viên - xem infra/README.md.

Biến môi trường

Một export trong shell ghi đè .env.workshop

Triệu chứng - bạn đặt một giá trị trong .env.workshop, nhưng container dùng một giá trị khác (thường là một OPENAI_API_KEY cũ, một biến LANGFUSE_*, hoặc CLICKHOUSE_PASSWORD).
Vì sao - docker compose nội suy ${VAR} từ shell của bạn trước, và một biến shell đã export sẽ THẮNG file.
Cách sửa - trong shell mà bạn chạy compose từ đó, hãy dùng unset OPENAI_API_KEY LANGFUSE_PUBLIC_KEY LANGFUSE_SECRET_KEY LANGFUSE_BASE_URL CLICKHOUSE_PASSWORD, rồi khởi động lại stack. Preflight sẽ cảnh báo khi nó phát hiện điều này.

Key trùng lặp trong .env.workshop

Triệu chứng - một giá trị bạn đặt trong file bị bỏ qua.
Vì sao - cùng một key xuất hiện hai lần; lần xuất hiện cuối thắng, khớp với ngữ nghĩa của docker compose (preflight đọc nó theo cùng cách).
Cách sửa - hãy xóa bản trùng lặp phía trước để chỉ còn lại giá trị bạn muốn.

Chat (module 08)

POST /api/chat trả về 503 kèm một gợi ý thiết lập

Triệu chứng - panel chat hiển thị một gợi ý thiết lập và /api/chat trả về 503; phần còn lại của ứng dụng vẫn ổn.
Vì sao - không có OPENAI_API_KEY nào được đặt trên back end.
Cách sửa - hãy thêm OPENAI_API_KEY vào .env.workshop, rồi chạy docker compose --env-file .env.workshop -f docker-compose.workshop.yml -f docker-compose.otel.yml up -d --build backend. Chat là tính năng duy nhất cần nó.

Không tạo được OpenAI key đầu tiên

Triệu chứng - OpenAI không cấp API key trên một tài khoản mới.
Vì sao - tài khoản mới cần xác thực số điện thoại một lần và không có tín dụng miễn phí.
Cách sửa - hãy hoàn tất xác thực số điện thoại, rồi vào Settings -> Billing: thêm một phương thức thanh toán và mua mức tối thiểu 5 đô la tín dụng trả trước. Hãy tắt auto-recharge (nó bật theo mặc định trong lúc thiết lập) để bạn không bao giờ bị tính phí vượt quá 5 đô la đã nạp.

MCP và OAuth (module 00 và 06)

401 trên endpoint MCP

Triệu chứng - truy cập https://mcp.clickhouse.cloud/mcp (hoặc /clickstack) trả về 401.
Vì sao - điều này là bình thường trước khi bạn hoàn tất luồng browser OAuth; endpoint có xác thực.
Cách sửa - hãy thêm server vào agent của bạn, rồi chạy luồng OAuth và cấp quyền trong browser, dùng câu lệnh của công cụ bạn:
- Claude Code - chạy /mcp, chọn server, và cấp quyền (hoặc claude mcp login <name>).
- Codex CLI - codex mcp login <name>.
- Cursor - hãy mở khung settings MCP và nhấn control authorize/login của server.
Đồng thời hãy xác nhận toggle Connect with MCP đang bật cho service của bạn.

Laptop công ty chặn MCP hoặc OAuth

Triệu chứng - agent của bạn không thêm được một MCP server, hoặc phần redirect của OAuth bị chặn.
Vì sao - một chính sách cho máy được quản lý chặn việc thêm MCP server hoặc OAuth ra ngoài.
Cách sửa - một máy cá nhân là phương án dự phòng nhanh nhất.

Windsurf không kết nối được qua HTTP thuần

Triệu chứng - Windsurf không kết nối được tới endpoint MCP, hoặc OAuth của nó không ổn định.
Vì sao - Windsurf kết nối qua mcp-remote chứ không qua streamable HTTP thuần.
Cách sửa - hãy dùng dạng câu lệnh mcp-remote: { "command": "npx", "args": ["-y", "mcp-remote", "https://mcp.clickhouse.cloud/mcp"] } (đổi /mcp thành /clickstack khi đấu nối ClickStack MCP ở module 06).