Xử lý sự cố

Chẩn đoán và khắc phục sự cố cài đặt, kết nối device và khi chạy flow.

Hãy bắt đầu với Help → Kiểm tra thiết lập…. Mục này tìm ra hầu hết các issue và dẫn tới cách sửa phù hợp. Xem Cài đặt.

Nếu vẫn cần trợ giúp, hãy gửi cho team ảnh chụp màn hình Kiểm tra thiết lập, file ~/Library/Logs/Astra Scout/server.log và file build.log được nhắc trong thông báo error.

Cài đặt và mở app

macOS báo app không mở được hoặc bị hỏng

Bản Astra Scout đều được ký và notarize, nên macOS chỉ hỏi một lần "downloaded from the Internet" rồi mở. Thông báo này nghĩa là bản bạn có không phải từ link tải của team (ví dụ một bản build phát triển trên máy được chuyền tay): tải lại DMG từ link ở trang Cài đặt.

"You have not agreed to the Xcode license agreements"

sudo xcodebuild -license accept
sudo xcodebuild -runFirstLaunch

iPhone thật

Signing for "WebDriverAgentRunner" requires a development team

Không có Team ID để ký WDA. Một app mở từ Finder không đọc MAESTRO_TEAM_ID từ .zshrc.

1. Đăng nhập Apple ID trong Xcode và tạo chứng chỉ Apple Development. Xem Device.
2. Mở Settings → iOS (mục Team ký app) và chọn một team, hoặc nhập Team ID thủ công. App hiện "Đang dùng: <Team ID>".
3. Kết nối lại iPhone. Bạn không cần khởi động lại app, và bản build fail không được dùng lại.

Thông báo error in ra đường dẫn chính xác của build.log. Với bản cài từ DMG, nó nằm dưới ~/Library/Application Support/Astra Scout/maestro-runner/cache/wda-builds/…/logs/build.log.

No profiles for 'com.facebook.WebDriverAgentRunner.xctrunner' were found hoặc No Account for Team

Xcode không tạo được provisioning profile. Hãy kiểm tra:

• Apple ID của team đó đã đăng nhập trong Xcode → Settings → Accounts (đăng nhập lại nếu đã hết hạn).
• iPhone đang cắm và mở trong Xcode → Devices and Simulators.
• Team ID trong Settings → iOS là team có chứng chỉ.
• Nếu bạn dùng Personal Team và thấy "Failed to register bundle identifier", hãy dùng team của công ty hoặc đợi vài ngày. Personal Team chỉ đăng ký được vài bundle ID mỗi tuần.

iPhone báo nhà phát triển chưa được tin cậy

Trên iPhone: Settings → General → VPN & Device Management → Apple Development: … → Trust, rồi kết nối lại.

Developer Mode disabled

Bật Settings → Privacy & Security → Developer Mode trên iPhone và khởi động lại máy.

Kết nối iPhone bị treo hoặc WDA không khởi động

• iPhone có thể đang khoá. Mở khoá và thử lại.
• Rút và cắm lại cáp, mở khoá máy, và kiểm tra trong Xcode → Devices and Simulators rằng máy không còn ở trạng thái "Preparing".
• Qua Wi-Fi, hãy cho phép System Settings → Privacy & Security → Local Network → Astra Scout, hoặc cắm cáp.

"iPhone screen is locked — unlock the iPhone and try again"

iPhone đã tự khoá và có passcode, nên Astra Scout không mở khoá được. Hãy mở khoá và chạy lại, và đặt Auto-Lock thành Never khi test. Các run bị chặn theo cách này có mã DEVICE_LOCKED và không bao giờ bị coi là bug của app.

Mirror iPhone báo error

Mirror dùng media stream của CoreDevice (Xcode 27 và iOS 27); hãy mở khoá iPhone và kiểm tra máy đã được tin cậy. iPhone đang khoá hoặc chưa kết nối được sẽ tự mirror khi phản hồi; iPhone không có media stream thì không mirror được nhưng flow vẫn chạy. Xem Device.

Mọi device

"Blocked: the driver is not responding"

Astra Scout kiểm tra driver trước mỗi run và cứ 15 giây một lần. Nếu nó không phản hồi, device hiện Đang kết nối lại driver và driver khởi động lại một lần. Nếu vẫn không được, bấm Kết nối lại. Điều này thường nghĩa là WDA đã bị tắt (Xcode hoặc simulator khởi động lại, hoặc một tool khác dùng cùng simulator). Hãy đóng tool kia hoặc dùng simulator khác.

Lần kết nối iOS đầu tiên mất nhiều thời gian

Lần đầu, maestro-runner build WebDriverAgent. Việc này mất khoảng 3 đến 10 phút. Các lần kết nối sau dùng lại bản build.

Android

Device unauthorized

Chấp nhận Allow USB debugging trên device. Nếu không thấy hộp thoại, tắt rồi bật lại USB debugging, chọn Revoke USB debugging authorizations, rồi cắm lại cáp. adb devices phải hiện device.

Không tìm thấy Android SDK

Đặt đường dẫn ở Settings → Android → Android SDK, hoặc đặt ANDROID_HOME.

AI

AI báo "Not signed in"

Chạy CLI trong Terminal và đăng nhập, rồi bấm Settings → AI → Agent → Quét lại. Bạn không cần mở lại app.

"No AI available…" trong một step AI

Không có AI CLI nào dùng được. Hãy cài và đăng nhập một CLI, rồi quét lại. Xem Trợ lý AI.

Plugin không kết nối được

Chạy /scout:setup. Lệnh này kiểm tra Astra Scout đang chạy, URL, MCP đã bật và token. Xem Plugin scout.

Jira

Xem Jira, sự cố thường gặp.