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.

Cách sửa khi app báo lỗi, cài không được, hoặc device không kết nối được. Mỗi mục là một thông báo lỗi và cách sửa.

Bắt đầu với Kiểm tra thiết lập. Mục này tìm ra hầu hết các issue và cho biết cách sửa từng cái. Xem Cài đặt.

1. Chọn Help > Kiểm tra thiết lập…. Sheet Kiểm tra thiết lập mở ra và điền dần khi các kiểm tra xong.
2. Tìm các hàng có biểu tượng đỏ hoặc cam. Mục bắt buộc ghi "(bắt buộc)". Mỗi hàng giải thích issue và cách sửa, và một số hàng có nút mở đúng mục trong Cài đặt.
3. Sửa mục đó, rồi bấm Kiểm tra lại.

Nếu vẫn chưa xử lý được, gửi cho team ảnh chụp màn hình Kiểm tra thiết lập, log của server và file build.log nêu trong thông báo error. Mở log của server bằng Help > Xem log server. File là ~/Library/Logs/Astra Scout/server.log và bắt đầu trống mỗi lần app khởi động.

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 cho biết bản đang dùng không đến từ link tải của team, ví dụ một bản build phát triển đượ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

"Không khởi động được Astra Scout"

Cửa sổ hiện Không khởi động được Astra Scout, một thông báo, và các nút Thử lại và Xem log server. Server cục bộ chạy device và flow không khởi động được, hoặc đã dừng giữa chừng.

1. Đọc thông báo. Các thông báo thường gặp:
   • "Một server Astra Scout khác đã trả lời trên cổng N". Một bản app khác, hoặc server chạy tay, đang chạy. Chúng dùng chung một thư mục dữ liệu nên không chạy cùng lúc được. Thoát cái kia.
   • "Server Astra Scout đã dừng (mã thoát N)", kèm các dòng cuối của log.
   • "Server Astra Scout không phản hồi kịp", kèm các dòng cuối của log.
   • "Server của Astra Scout không còn phản hồi". Server đang chạy rồi biến mất.
   • "Không còn cổng cục bộ trống cho server Astra Scout."
2. Bấm Xem log server để mở server.log. File này cũng mở được bằng Help > Xem log server.
3. Sửa nguyên nhân, rồi bấm Thử lại.

Nếu thay vào đó một hộp thoại ghi Astra Scout đang chạy, một server Astra Scout khác đã trả lời trên cổng đó. Thoát nó rồi mở lại app.

Mở Astra Scout lần thứ hai không tạo bản thứ hai. Cửa sổ đầu tiên được đưa lên trước. Mỗi thư mục dữ liệu chỉ chạy một bản app.

iOS device

Signing for "WebDriverAgentRunner" requires a development team

Để điều khiển iOS device, Astra Scout cần "ký" WebDriverAgent (WDA, app nhỏ chạy trong iOS device) bằng một team Apple Developer. Team được xác định bằng Team ID, một mã 10 ký tự. Lỗi này xuất hiện khi app chưa biết dùng team nào. Panel kết nối hiện error, đường dẫn của build.log và nút Mở cài đặt iOS….

1. Đăng nhập Apple ID trong Xcode và tạo chứng chỉ Apple Development. Xem Device.

2. Bấm Mở cài đặt iOS…, hoặc chọn Astra Scout > Cài đặt… rồi bấm iOS. Trong Team ký app, bấm một hàng team. Tự động dùng team duy nhất trong Keychain.

3. Nếu team không có trong danh sách, bấm Quét lại, hoặc bấm Team ID khác…, gõ Team ID trong popover và bấm Lưu. Dòng "Đang dùng: …" cho biết Team ID mà lần kết nối sau sẽ dùng.

   

4. Kết nối lại iOS device (bấm Kết nối lại trong panel kết nối). 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. Xem thêm Chọn team trong app.

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

Xcode không tạo được provisioning profile, thứ cho phép app chạy trên iOS device. Panel kết nối giải thích vấn đề bằng ngôn ngữ của app và liệt kê các step. 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).
• iOS device đang cắm và mở trong Xcode > Window > Devices and Simulators.
• Team ID trong Cài đặt > iOS là team có chứng chỉ.
• "Failed to register bundle identifier" là cùng loại issue: chọn team khác trong Cài đặt > iOS.

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

Trên iOS device: 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 iOS device và khởi động lại máy.

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

• iOS device 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 > Window > Devices and Simulators rằng máy không còn ở trạng thái "Preparing".
• Qua Wi-Fi, cho phép System Settings > Privacy & Security > Local Network > Astra Scout, hoặc cắm cáp.

"iOS device screen is locked — unlock the iOS device and try again"

iOS device đã tự khoá và có passcode, nên Astra Scout không mở khoá được. Trong app tiếng Việt, thông báo ghi "Màn hình iOS device đang khoá". Mở khoá và chạy lại. Đặ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. Xem Khi iOS device tự khoá.

Mirror iOS device báo error

Mirror dùng media stream của CoreDevice (Xcode 27 và iOS 27); mở khoá iOS device và kiểm tra máy đã được tin cậy. iOS device đang khoá hoặc chưa kết nối được sẽ tự mirror khi phản hồi; iOS device 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 (WDA trên iOS, driver DeviceLab trên Android) trước mỗi run và cứ 15 giây một lần khi có device đang kết nối. 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, thông báo của run ghi Device không khả dụng ("Driver của device không phản hồi và kết nối lại không giải quyết được."), và run không bắt đầu.

1. Bấm Kết nối lại trong thông báo hoặc trong panel device.
2. Nếu vẫn fail, tìm nguyên nhân. Thường 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). Đóng tool kia hoặc dùng simulator khác.

Xem Tình trạng driver và kết luận (verdict).

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

Lần đầu, maestro-runner build WebDriverAgent (WDA, một app nhỏ chạy trong device để nhận lệnh tap) nên lâu hơn các lần sau. 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 hộp thoại không hiện, 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

1. Chọn Astra Scout > Cài đặt… rồi bấm Android.
2. Trong Android SDK, đọc Trạng thái. Nó ghi "Không tìm thấy" khi không phát hiện SDK nào.
3. Bấm Chọn thư mục… và chọn thư mục SDK (mặc định ~/Library/Android/sdk), hoặc gõ vào Đường dẫn tuỳ chỉnh. "Đường dẫn hợp lệ" xác nhận đường dẫn đúng. Để trống Đường dẫn tuỳ chỉnh để phát hiện SDK từ ANDROID_HOME hoặc vị trí mặc định.
4. Nếu SDK được cài khi Cài đặt đang mở, bấm Kiểm tra lại.

AI

AI báo "Not signed in"

Chạy CLI trong Terminal và đăng nhập. Rồi chọn Astra Scout > Cài đặt…, bấm AI, và bấm Quét lại dưới Agent. Không cần mở lại app. Hàng đó đổi thành Sẵn sàng.

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

Một step AI (assertWithAI, assertNoDefectsWithAI, extractTextWithAI) fail với "Không có AI dùng được cho step kiểm tra AI: …". Không có AI CLI nào dùng được. Với optional: false, run bị chặn (Bị chặn). Mặc định step là optional nên run vẫn chạy tiếp và hiện warning. Cài và đăng nhập một CLI, rồi bấm Quét lại. Xem Trợ lý AI.

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

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

• Cài đặt > AI > Kết nối MCP: Bật kết nối từ CLI (MCP) đang bật.
• Cổng 5050 đang bận: trang ghi "Không dùng cổng mặc định 5050". Giải phóng cổng và mở lại app, hoặc đặt SCOUT_MCP_URL. Xem Nếu Astra Scout không ở cổng 5050.
• Mọi lời gọi bị từ chối (lỗi 401) sau khi bấm Tạo token mới: CLI vẫn giữ token cũ. Đặt lại SCOUT_MCP_TOKEN, hoặc dùng Môi trường shell > Thêm vào profile shell, rồi khởi động lại CLI. Xem MCP token.
• Hoạt động từ CLI trên cùng trang liệt kê các lời gọi gần nhất và kết quả, cho biết CLI có tới được Astra Scout hay không.

Xem Plugin scout.

Đăng nhập Google

"… is not allowed to use Astra Scout"

App báo "… không được phép dùng Astra Scout. Hãy nhờ admin thêm tài khoản này, hoặc đăng nhập bằng tài khoản khác." Danh sách đăng nhập của team không có tài khoản này. Nhờ owner của team thêm email ở Thành viên, hoặc domain của email ở Domain được đăng nhập, trên trang web builds. Xem Member và Cài đặt. Sau đó đăng nhập lại, hoặc đăng nhập bằng tài khoản Google khác.

Trang web builds cũng có thể báo "Email của tài khoản Google này chưa được xác minh." Email của tài khoản Google chưa được xác minh. Xác minh email trong tài khoản Google, rồi đăng nhập lại.

Builds

Các triệu chứng của cửa sổ Builds có bảng riêng: Builds, xử lý sự cố. Bảng này có "Đăng nhập để xem build của team", "Chưa có bản build iOS", APP_FILE_REQUIRED và nút Cài lên bị mờ. Khi iOS device không có trong provisioning profile của bản build, xem Khi iOS device không có trong profile. Với upload bằng scout-build và Xcode, xem Chia sẻ build cho tester, xử lý sự cố.

Team Sync

Xem Team Sync, xử lý sự cố cho mục Sync bị thiếu, Chưa liên kết, Sync tắt, file trong File không sync được và "Bản trên cloud vừa đổi". Với file bị sửa trên hai Mac, xem Conflict. Với sync đã giữ lại một đợt xoá hàng loạt, xem File bị xoá bị giữ lại.

Mạng

Astra Scout chạy flow trên máy Mac và không có telemetry. Đăng nhập, Builds và Team Sync dùng cloud của team (xem FAQ). Đây là những thứ duy nhất dùng mạng, và mỗi thứ cần kết nối riêng:

Gì	Khi nào	Kết nối tới đâu
AI CLI	Khi dùng chat, lệnh AI, tự sửa hoặc Explore	Nhà cung cấp riêng của nó, do CLI đặt
Jira	Đăng nhập và gửi báo cáo bug	auth.atlassian.com và api.atlassian.com
Amplitude	Tra cứu user, import taxonomy và chuyển tiếp event test, với project đã thêm trong Cài đặt	amplitude.com và api2.amplitude.com (vùng EU: analytics.eu.amplitude.com và api.eu.amplitude.com)
App Store Connect	Sandbox tester, với API key đã thêm trong Cài đặt	api.appstoreconnect.apple.com
Team API	Đăng nhập, Builds (danh sách, tải bản build và thông báo bản build mới), upload từ trang web và scout-build, và Team Sync	astra-scout-api.hunghoang.workers.dev
Cập nhật và tải về	Kiểm tra bản cập nhật mỗi ngày một lần ở bản release và với Astra Scout > Kiểm tra bản cập nhật…, và tải Astra Scout hoặc script cài scout-build	pub-41fdab24ed354d9cbc36e595de529780.r2.dev

File build được tải qua team API, bằng link hết hạn sau 10 phút, nên kho lưu trữ của team không cần địa chỉ riêng. Nếu một tính năng fail sau tường lửa hoặc proxy, cho phép các địa chỉ trong bảng này. Để tắt kiểm tra cập nhật hằng ngày, bỏ chọn Tự động kiểm tra bản cập nhật trong Cài đặt > Chung.

Jira

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