Xử lý sự cố và câu hỏi thường gặp
Trang này tổng hợp triệu chứng, nguyên nhân và cách xử lý theo từng nhóm sự cố, để bạn biết khi nào tự sửa được và khi nào cần gọi owner, admin hoặc sysadmin.
Đối tượng: mọi role. Mỗi mục ghi triệu chứng → nguyên nhân → xử lý, kèm khi nào tự làm được và khi nào gọi owner/admin/sysadmin.
Bạn đang gặp loại nào? Phân loại 30 giây
1. Quyền và truy cập
| Triệu chứng | Nguyên nhân | Xử lý |
|---|---|---|
| 403 ở mọi thứ | Chưa có membership; phân quyền fail-closed | Nhờ owner cấp quyền hoặc dùng AGENTBOARD_BOOTSTRAP_OWNERS; dev local bật AGENTBOARD_DEV_IDENTITY=1 |
Là member nhưng Approve bị chặn | Đúng thiết kế: approve cần admin + human | Nhờ cấp admin nếu bạn thực sự là người duyệt |
| Script CI dùng service token approve → 403 | Đúng thiết kế, không có bypass (scope gate:approve không tồn tại; token phân giải về system) | Chuyển bước approve cho người thật |
| Không xoá được owner cuối (409) | Chống tự khoá | Cấp owner cho người khác trước rồi xoá |
| Pentest header giả approve không 403 | Sự cố bảo mật P0 | Dừng nghiệm thu — sysadmin kiểm tra JWT verify + nginx strip header + loopback |
Chi tiết: Vì sao Human Gate không bypass được.
2. Agent và task
| Triệu chứng | Nguyên nhân | Xử lý |
|---|---|---|
| Task tạo được nhưng không chạy | Không có agent CLI nào trên PATH | GET /api/agents kiểm tra; production build từ Dockerfile.agents; liên hệ sysadmin |
| Agent chạy nhưng kết quả tệ | description chung chung, thiếu AC; .board/wiki/INDEX.md rỗng | Viết lại mô tả + AC cụ thể + non-goals; nạp tài liệu vào Wiki trước |
| Agent sửa file ngoài phạm vi | Thiếu giới hạn | Đặt ALLOWED_REPO_ROOTS (sysadmin); viết non-goals trong mô tả |
| Agent treo / lặp vô nghĩa / đi sai hướng | Prompt thiếu, yêu cầu đổi giữa chừng | Khi agent treo: Follow-up → Stop+sửa mô tả → Request Changes → cleanup-worktree → chờ lease 30s |
Task quá 3 vòng rework → needs-human | Chống lặp vô tận | Làm tay trong worktree, commit, approve lại |
git merge báo "Committer identity unknown" | Container thiếu git identity system | docker exec agentjira_server git config --system user.email agentjira@localhost + user.name AgentJira |
| Server crash khi agent chạy — mất việc? | Không mất | Lease 30s hết hạn, boot recovery về idle + Activity system_recovery, worktree giữ nguyên → bấm Run lại |
| Xoá task rồi lấy lại? | Không | Dùng Archive thay Delete |
3. Planner (AI lập kế hoạch)
| Triệu chứng | Nguyên nhân | Xử lý |
|---|---|---|
[LLM VCR ERROR] Cassette cache miss | Đang mode replay (mặc định) | Sysadmin đặt AGENTBOARD_LLM_MODE=live + key + model |
| Apply Plan bị từ chối "cycle detected" | dependsOn tạo vòng A→B→A | Sửa trong PlanDraftEditor rồi apply lại |
| Plan quá chung chung | Không research codebase, Wiki trống | Bật research; nạp kiến trúc vào Wiki trước |
| Model OpenRouter không dùng được cho Planner | Không hỗ trợ structured outputs | Chạy Diagnose #3; preflight cảnh báo LLM_OPENROUTER_MODEL_UNVERIFIED |
4. Wiki và tri thức
Đọc kỹ — lỗi ở đây thường CHẾT LẶNG
Suy biến mềm Arkon: khi Arkon down hoặc Space không link, hệ thống không báo 500 mà bỏ qua Wiki, Board vẫn 200 OK. Phát hiện bằng 4 dấu hiệu:
- Tab Wiki trống trong khi biết Department có trang.
.board/wiki/INDEX.mdchứa "No wiki pages available for this space".- Activity task có
system_warning. - Log server có
[preflight] ARKON_URL_*.
Kiểm tra nhanh:
docker exec agentjira_server node -e "fetch('http://arkon_api:5055/health').then(r=>console.log(r.status)).catch(e=>console.log('DOWN',e.message))"
| Triệu chứng | Nguyên nhân | Xử lý |
|---|---|---|
| Tab Wiki trống (đủ 4 dấu hiệu trên) | Arkon down / sai ARKON_API_URL / thiếu link | Sysadmin kiểm tra health, env, link Space↔Department |
| Semantic search không kết quả | Chưa nhập Embedding key (riêng, khác LLM key) ở Settings → Model Catalog | Nhập key, thử lại |
| Đổi model embedding rồi search hỏng | Vector khác số chiều | Đừng đổi sau khi đã nạp; muốn đổi: Online Re-embed Migration + Diagnose #6 trước |
Nguồn upload báo error | Embed thất bại — trang Wiki đã ghi, chỉ thiếu vector | Dán key embedding thật → Retry (chỉ chạy lại commit, idempotent) |
| Draft conflict khi approve | Hai người sửa cùng trang | Vào Wiki Rebase gỡ conflict rồi merge lại |
| Deep wiki 404 toàn bộ (revisions/rollback/graph/lint/branches/merge/close) | Đúng thiết kế khi AGENTBOARD_WIKI_DEEP_UI tắt — cờ tắt nghĩa là bề mặt không tồn tại | Bật cờ nếu cần; /api/wiki/pages + /api/wiki/drafts vẫn 200 là bình thường (TẮT = Phase 1) |
Rollback / merge / duyệt draft 502 kèm detail về quyền | 403 cổng Arkon nổi lên (thiếu wiki:write:all), không phải Arkon sập | Kiểm global_role trong Arkon + bật AGENTBOARD_ARKON_RBAC_SYNC + đợi 1 nhịp reconciler; CẤM nâng role='admin' Arkon (vỡ lọc department) |
Cờ đã nằm trong .env mà tính năng không đổi | Biến chưa tới container (thiếu trong environment: của compose) | docker exec agentjira_server printenv | grep AGENTBOARD_ rồi curl -s localhost:8081/api/features — sửa compose, không sửa .env |
Nguồn kẹt processing | Phân biệt đỗ đúng với kẹt thật: awaiting_approval (vượt ngưỡng token) và plan_ready (luôn đỗ) là cổng chờ người | Approve ở UI; chỉ coi là lỗi khi Arkon đã trạng thái cuối >20s mà board chưa hội tụ |
5. Realtime, mạng, dữ liệu
| Triệu chứng | Nguyên nhân | Xử lý |
|---|---|---|
| Board không tự cập nhật | WebSocket 403 | Hostname công khai phải trong ALLOWED_HOSTS; DevTools → Network → WS |
Header báo No updates | Server từ chối room — bạn không phải member Space đó | Nhờ owner thêm vào Space |
Header báo No updates yet quá 5s | Subscribe treo — danh tính chưa giải được lúc upgrade (IDENTITY_PENDING: JWKS chậm hoặc thiếu TRUST_PROXY_IDENTITY sau proxy) | Kiểm log server, thử reload sau khi danh tính ổn |
| HTTP 429 | Rate limit 3000 req/phút/IP | Tăng RATE_LIMIT_MAX nếu thật cần |
| Backup ở đâu | 3 stores độc lập | agentjira_db + arkon_postgres + arkon_minio — lệnh ở runbook §5 |
6. Giới hạn đã biết Phase 1 (không phải bug)
| Giới hạn | Hiện trạng | Cách xoay |
|---|---|---|
| Bơm Wiki vào worktree (deadline 8s) | đã nối | — |
wikiProposals → draft Arkon | đã nối (sau complete) | — |
| Reviewer Agent độc lập | đã nối (auto cần LLM thật) | Người duyệt cuối ở human-gate |
Repair loop result.json (2 vòng, 5m/vòng) | đã nối | Fallback regex nếu vẫn sai |
| MCP write trực tiếp (K5) | chưa triển khai (đã hoãn) | dùng đường file |
@mention subtask, theo dõi chi phí token | chưa có | tạo task con tay; xem dashboard provider |
withRepoLock 1 process | không chống git tay / nhiều instance | không git tay trong repo gốc khi agent đang chạy |
| Test Arkon (21 router, gate pytest xanh) | kiểm tay luồng quan trọng | theo MANUAL-TEST-PLAN |
Chi tiết: Giới hạn đã biết Phase 1.
7. Khi nào gọi ai
| Gặp | Gọi |
|---|---|
| Cần quyền, đổi role, mất admin Space | Space owner |
| Diff chưa đạt, rework/merge conflict sâu | Approver |
| Deploy, secret, JWT/proxy, backup, Arkon down, thiếu key, agent CLI thiếu | SysAdmin |
| Draft Wiki/skill cần duyệt, plan MRP lạ, embedding/search hỏng | Knowledge manager |
8. Nhờ xử lý thì gửi kèm gì
Đừng chỉ gửi ảnh chụp màn hình. Một báo lỗi xử lý được trong 5 phút gồm:
1. Bạn là ai: GET /api/me (actor id + type)
2. Đang ở đâu: Space + task id (hoặc URL trang)
3. Làm gì thì lỗi: 3 bước click / 1 lệnh curl tái hiện
4. Server nói gì: status + {"error": "..."} đầy đủ
5. Log phía server: docker compose logs agentjira_server --since 10m | grep -iE 'error|rbac|403'
6. Phía browser (nếu UI): DevTools → Console + tab Network (request đỏ)
Vẫn kẹt? Đi đúng cửa ở §7 kèm đủ 6 mục §8 — owner/admin/sysadmin xử lý nhanh gấp nhiều lần một câu "sao em bị lỗi".