Khắc phục sự cố (Troubleshooting)

Bài viết này tổng hợp các lỗi thường gặp khi sử dụng TLGeo Agent với QGIS, được nhóm theo từng nhóm tính năng QGIS. Mỗi lỗi có mô tả, nguyên nhân, và cách xử lý cụ thể.

Lỗi kết nối và khởi động

Server không khởi động được

Lỗi: OSError: [Errno 98] Address already in use

Nguyên nhân: Port 13001 đã bị chiếm bởi process khác.

Cách xử lý:

1. Tìm process đang dùng port:

   # macOS / Linux
   lsof -i :13001
   
   # Windows
   netstat -ano | findstr :13001

2. Tắt process đó, hoặc đổi PORT trong .env:

   PORT=13002

ModuleNotFoundError khi chạy Python

Lỗi: ModuleNotFoundError: No module named 'fastapi'

Nguyên nhân: Chưa cài dependencies.

Cách xử lý:

# Kích hoạt virtual environment
source venv/bin/activate  # macOS/Linux
# hoặc
venv\Scripts\activate     # Windows

# Cài lại
pip install -r requirements.txt

Lỗi Python version

Lỗi: SyntaxError hoặc các lỗi liên quan đến Python 3.10+

Nguyên nhân: Đang dùng Python < 3.10.

Cách xử lý:

1. Kiểm tra version: python --version
2. Cài Python 3.10+: https://www.python.org/downloads/

Không kết nối được tới QGIS Plugin

Lỗi: WebSocket connection failed, plugin không nhận lệnh.

Nguyên nhân:

• QGIS chưa mở hoặc plugin chưa được kích hoạt
• Sai port/host trong cấu hình plugin
• Firewall chặn localhost

Cách xử lý:

1. Kiểm tra QGIS đã mở chưa
2. Kiểm tra plugin đã enable chưa (Plugins → Manage and Install Plugins)
3. Restart QGIS
4. Xem log của plugin

Lỗi API key / LLM

”Invalid API key” / 401 Unauthorized

Nguyên nhân: API key sai, hết hạn, hoặc không có quyền.

Cách xử lý:

1. Lấy lại API key từ dashboard của provider
2. Cập nhật file .env:

   LLM_API_KEY=new-key-here

3. Restart server

”Model not found” / 404

Nguyên nhân: Tên model trong LLM_MODEL không tồn tại.

Cách xử lý:

• Thử model phổ biến: gpt-3.5-turbo, MiniMax-M3
• Kiểm tra danh sách model của provider

”Rate limit exceeded” / 429

Nguyên nhân: Gọi API quá nhiều trong thời gian ngắn.

Cách xử lý:

1. Đợi 1-2 phút rồi thử lại
2. Nâng cấp gói LLM
3. TODO: Thêm rate limiting ở Agent level?

Timeout khi gọi LLM

Nguyên nhân: LLM phản hồi chậm, hoặc mạng chậm.

Cách xử lý:

1. Thử lại với câu hỏi ngắn hơn
2. Dùng model nhanh hơn (gpt-3.5 thay vì gpt-4)
3. Kiểm tra kết nối mạng

Lỗi khi xem dữ liệu

”Layer not found”

Nguyên nhân: Tên layer sai, hoặc layer chưa được mở.

Cách xử lý:

Hỏi Agent: Liệt kê tất cả layer đang mở

Sau đó dùng tên chính xác trong câu hỏi tiếp theo.

”File not found”

Nguyên nhân: Đường dẫn file sai.

Cách xử lý:

1. Kiểm tra đường dẫn tuyệt đối
2. Dùng tool qgis_find_file để tìm file
3. Trên Windows, dùng \\ thay vì /:

   Đường dẫn đúng: C:\\data\\file.shp

“Invalid CRS”

Nguyên nhân: File không có CRS, hoặc CRS bị lỗi.

Cách xử lý:

1. Mở QGIS UI → Layer Properties → Source
2. Gán CRS thủ công
3. Hoặc hỏi Agent: “Gán CRS EPSG:4326 cho layer X”

WMS connection timeout

Nguyên nhân: Server WMS chậm, hoặc firewall chặn.

Cách xử lý:

1. Thử server WMS khác
2. Kiểm tra URL chính xác
3. Kiểm tra proxy/firewall

Lỗi khi explore/compose maps

Zoom không hoạt động

Nguyên nhân: Layer có CRS không xác định.

Cách xử lý:

Hỏi: Gán CRS EPSG:4326 cho layer X, sau đó zoom tới layer đó

“No features selected”

Nguyên nhân: Query không trả về feature nào.

Cách xử lý:

1. Kiểm tra giá trị thực tế trong cột:

   Hỏi: Liệt kê 10 giá trị phổ biến nhất trong cột "trang_thai"

2. Chú ý chữ hoa/thường, khoảng trắng
3. Dùng đúng tên cột

Style không áp dụng

Nguyên nhân: Layer đang ở chế độ read-only, hoặc style rule sai syntax.

Cách xử lý:

1. Mở khóa layer (Layer → Toggle Editing)
2. Kiểm tra lại QGIS expression
3. Test style trong QGIS UI trước

”Cannot compute extent”

Nguyên nhân: Layer có geometry không hợp lệ.

Cách xử lý:

Hỏi: Kiểm tra geometry có lỗi trong layer X

Sau đó fix hoặc loại bỏ feature lỗi.

Lỗi khi phân tích dữ liệu

”Query returns no result”

Nguyên nhân: Điều kiện trong SQL quá chặt, hoặc sai tên cột.

Cách xử lý:

1. Thử bỏ bớt điều kiện
2. Kiểm tra tên cột chính xác:

   Hỏi: Liệt kê các cột của layer X

3. Test query trong DB Manager trước

”SQL syntax error”

Nguyên nhân: SQL không hợp lệ cho database backend.

Cách xử lý:

• Shapefile/GeoPackage: SQLite/SpatiaLite syntax
• PostGIS: PostgreSQL syntax
• Ví dụ sai: LIMIT 5 không work trên một số database
• Hỏi Agent: “Query này sai syntax, sửa giúp tôi"

"Timeout during analysis”

Nguyên nhân: Dữ liệu quá lớn, hoặc thuật toán chậm.

Cách xử lý:

1. Lọc trước khi phân tích
2. Chạy trong background
3. Dùng spatial index

”SAGA algorithm not available”

Nguyên nhân: Chưa cài SAGA plugin.

Cách xử lý:

1. Plugins → Manage and Install Plugins
2. Tìm “SAGA”
3. Install

CRS mismatch trong geoprocessing

Lỗi: “Layer X has different CRS”

Cách xử lý:

Hỏi: Reproject layer X sang EPSG:4326 (cùng CRS với layer Y)

Lỗi khi execute Python script

”NameError: name ‘X’ is not defined”

Nguyên nhân: Thiếu import.

Cách xử lý:

Hỏi: Import thư viện cần thiết cho code

“IndexError: list index out of range”

Nguyên nhân: Layer không tồn tại.

Cách xử lý:

1. Kiểm tra tên layer chính xác
2. Dùng code an toàn:

   layers = QgsProject.instance().mapLayersByName('my_layer')
   if not layers:
       print("Layer not found")
   else:
       layer = layers[0]

“AttributeError: ‘NoneType’ object has no attribute ‘X’”

Nguyên nhân: Feature thiếu giá trị.

Cách xử lý:

if feature['column'] is not None:
    # process

Permission denied khi ghi file

Cách xử lý:

1. Đổi thư mục output
2. Chạy với quyền admin
3. Kiểm tra file có đang mở bởi app khác không

Script chạy quá lâu

Cách xử lý:

1. TODO: Có timeout không? Cần confirm với team dev
2. Chia nhỏ script
3. In log thường xuyên để theo dõi

Lỗi khi tạo / xuất dữ liệu

”Layer is read-only”

Cách xử lý:

1. Layer → Toggle Editing
2. Hoặc tạo bản sao layer trước

”Field already exists”

Cách xử lý:

• Dùng tên cột khác, hoặc xóa cột cũ trước

Export ra Shapefile bị cắt tên cột

Nguyên nhân: Shapefile giới hạn tên cột 10 ký tự.

Cách xử lý:

• Dùng GeoPackage thay thế
• Hoặc đổi tên cột ngắn hơn

DXF export mất style

Cách xử lý:

• Dùng QGIS UI cho tác vụ DXF-Export (nhiều tùy chọn nâng cao)

Lỗi plugin / WMS

Plugin không load

Cách xử lý:

1. Plugins → Manage and Install Plugins
2. Tìm plugin cần thiết
3. Install và Enable
4. Restart QGIS

”MetaSearch: connection failed”

Cách xử lý:

1. Kiểm tra URL CSW server
2. Test với browser trước
3. Kiểm tra proxy

Hiệu năng chậm

Agent phản hồi chậm

Nguyên nhân: LLM phản hồi chậm, hoặc câu hỏi phức tạp.

Cách xử lý:

1. Đợi (có thể mất 10-30s cho câu phức tạp)
2. Chia câu hỏi thành nhiều bước nhỏ
3. Dùng model nhanh hơn

QGIS chậm khi có nhiều layer

Cách xử lý:

1. Ẩn các layer không dùng
2. Dùng spatial index
3. Đơn giản hóa style

Phân tích dữ liệu lớn rất chậm

Cách xử lý:

1. Lọc trước: select_features với điều kiện
2. Chạy trong background
3. Dùng PostGIS thay shapefile (nhanh hơn nhiều)
4. Cân nhắc dùng cloud processing

Khôi phục khi gặp sự cố nghiêm trọng

Reset toàn bộ session

1. Đóng QGIS
2. Tắt server Agent (Ctrl+C trong terminal)
3. Xóa file conversations.db nếu muốn (lưu ý: mất lịch sử chat)
4. Khởi động lại server
5. Mở lại QGIS

Backup dự án

Trước khi thực hiện thay đổi lớn:

Hỏi: Backup tất cả layer hiện tại ra /backup/ trước khi tôi chỉnh sửa

Liên hệ hỗ trợ

TODO: Cập nhật thông tin liên hệ hỗ trợ:

• Hotline/Zalo
• Email
• Issue tracker

Câu hỏi nhanh khi gặp lỗi

Khi gặp lỗi, hỏi Agent:

Tôi gặp lỗi: [paste error message]
Bạn có thể giải thích và gợi ý cách xử lý không?

Agent có thể đọc log và đề xuất cách fix nhanh hơn.

TODO cần bạn xác nhận

• Thêm section cho từng lỗi cụ thể từ feedback người dùng
• Có cần log viewer tool không?
• Có cần auto-report lỗi về backend không?

Liên kết

• Bài 12: Cấu hình môi trường
• Bài 15: Câu hỏi thường gặp
• Bài 13: Viết câu hỏi hiệu quả