Known issues

Known limitations and workarounds for Maestro on different platforms.

Use this page to quickly find known limitations and their workarounds when debugging Maestro tests. Issues are grouped by cross-platform, Android, and iOS.

Report a new bug

If you find a bug that is not listed on this page, report it here.

Cross-platform

App does not launch

What is happening

The app does not start. Maestro may report that the app is not installed or that the appId is incorrect. The correct identifier depends on the app type.

How to find the appId

To find the appId on Android:

• Run adb shell pm list packages to list installed packages.

• Search for the appId or filter by name using adb shell pm list packages | grep <name>, replacing <name> with the desired app name.

On iOS:

• Run xcrun simctl listapps booted | grep CFBundleIdentifier to list installed apps.

• Search for the app ID or filter by name using xcrun simctl listapps booted | grep CFBundleIdentifier | grep <name>, replacing <name> with the desired app name.

Maestro is not compatible with all Java versions

What is happening

Maestro may fail or behave unexpectedly when used with very old or very new Java versions.

Workaround

We recommend Java 17 or 21. If you require different versions to run other applications, use jenv or sdkman to manage multiple Java versions. See the Maestro guide on installing and using sdkman.

Android

Below are the known issues that affect Maestro when testing Android apps.

Failed to activate device

What is happening

When testing on a physical Android device, you may see the error Failed to active device. This seems more prevalent on Redmi devices.

Workaround

To resolve it:

• Open Developer Settings (where you enabled ADB debugging).

• Tap Reset to default values between 5 and 8 times

• Tap Disable permission monitoring option when it appears

Google Maps crashes on Maestro Cloud

What is happening

An app that displays a Google Map may crash when the map screen opens on Maestro Cloud, while working fine on physical devices and local emulators. The crash is:

java.lang.NoClassDefFoundError: Failed resolution of: Lorg/apache/http/ProtocolVersion;

thrown from inside Google's Maps module (dynamite_mapsdynamite), not from your app's own code.

Why it happens

Maestro Cloud runs on google_apis Android emulator images. Google's Maps module still references a legacy library (org.apache.http), which these images don't put on your app's classpath by default as it's opt-in. Physical devices and Play-Store emulator images provide that library automatically, so the crash only appears on Cloud.

Workaround

Declare the library in your app's AndroidManifest.xml, inside the <application> tag:

<uses-library android:name="org.apache.http.legacy" android:required="false" />

This makes the library available to the Maps module. It is harmless on physical devices and Play-Store images (android:required="false" means the app still installs where the library isn't needed), so it's safe to keep in all builds.

Companion driver APK fails to install (INSTALL_PARSE_FAILED_NO_CERTIFICATES)

What is happening

Before running any flow, Maestro installs a small companion driver app onto the Android device. On hardened enterprise, MDM-locked, or fintech/POS devices that enforce strict APK signature verification at the kernel level, this install is rejected and Maestro cannot start. The error looks like:

Failed to install apk .../maestro-app*.apk: Install failed: Failure [INSTALL_PARSE_FAILED_NO_CERTIFICATES: ... using APK Signature Scheme v2: SecondarySignatureV2Verify fail]

Limitation

The companion driver is required. Maestro relies on it for both device observations and interactions. Devices that block installation of the companion APK are not supported.

Toggling Verify apps over USB or Verify bytecode of debuggable apps does not typically help with restrictions of this kind, and manually re-signing the APK may be flagged as tampering.

Workaround

Use a standard (non-hardened) Android device or emulator for your Maestro tests, or run against Maestro Cloud.

Text input is not supported for Unicode

What is happening

When testing Android apps, the inputText command does not work as expected when the input contains non-ASCII characters.

Limitation

On Android, only ASCII characters are supported. Follow this GitHub issue for updates.

Unable to clear state

What is happening

When testing on a physical Android device, you may see the error (Unable to clear state for app <package>) when running:

- clearState

or

- launchApp
   clearState: true

Workaround

This issue is common on some physical devices from Oppo and Realme. To resolve it, return to the Developer Settings where ADB debugging was enabled:

1. Open Developer Settings (where you enabled ADB debugging).

2. Disable Verify apps over USB.

3. If the error persists, enable Disable permission monitoring.

WebView elements cannot be seen by Maestro

What is happening

In some cases, web content rendered inside a WebView may not be fully accessible through the OS-native accessibility APIs that Maestro relies on. As a result, Maestro may have difficulty detecting or interacting with elements on the page.

Workaround

Enable WebView hierarchy inspection via Chrome DevTools. Add androidWebViewHierarchy: devtools at the top of your flow file to allow Maestro to use Chrome’s DevTools to better understand and interact with the on-screen web content.

androidWebViewHierarchy: devtools
---
- tapOn: "Open WebView"
- assertVisible: "My button"

Support for androidWebViewHierarchy in Maestro Studio Desktop is not yet available

iOS

Below are the known issues that affect Maestro when testing iOS apps.

hideKeyboard command is flaky

What is happening

The hideKeyboard command does not always dismiss the keyboard.

iOS does not provide a native API to hide the keyboard. Maestro attempts to dismiss it by scrolling from the center of the screen, which is not always reliable.

Update

Maestro has updated the hideKeyboard command to verify that the keyboard is actually hidden. If the system fails to dismiss the keyboard, the command will now fail the test.

This behavior is currently only available on Maestro Cloud. It will be released to Maestro CLI and Maestro Studio soon.

If your tests start failing after this release, replace the command:

- hideKeyboard

With tapping on a non-interactive element:

# Instead of hideKeyboard, tap a safe area
- tapOn: "Header Title"

Workaround

Use tapOn with the point parameter to tap on a non-tappable area of the screen (for example, above or beside the keyboard), mimicking how a user would dismiss it.

Lists that fetch data on scroll ( UITableView / UICollectionView )

What is happening

Apps that implement pagination (that is, fetching data as the user scrolls) inside UITableView or UICollectionView may exhibit unexpected behavior when tested with Maestro. This can include data being fetched at unintended times, lists appearing to hang, or user flows breaking during test execution.

This behavior is caused by a bug in the XCTest framework where the willDisplayCell method of UITableView / UICollectionView is triggered whenever UI test APIs are invoked. Because Maestro relies on XCTest under the hood, these unintended calls can interfere with pagination logic and lead to flaky or incorrect behavior.

Workaround

In willDisplayCell, ensure that data-loading logic runs only when the cell is actually visible. Use UITableView.indexPathsForVisibleRows or UICollectionView.indexPathsForVisibleItems and verify that the current indexPath is included before fetching data:

// This function should be implemented in a class conforming to UITableViewDelegate
// in case of UICollectionView `collectionView(_:willDisplay:forItemAt:)` from
// UICollectionViewDelegate should be used
func tableView(_ tableView: UITableView,
                   willDisplay cell: UITableViewCell,
                   forRowAt indexPath: IndexPath) {
  // additional check whether the cell is currently visible or not is needed
  // to make sure calls caused by XCTest or other random tableView reloads
  // do not unintentional data fetch request
  guard let visibleIndexPaths = tableView.indexPathsForVisibleRows,
            visibleIndexPaths.contains(indexPath),
            <additional checks that were previosly there> else { return }
        
  print("load new data..")
}

inputText fails on password fields (secureTextEntry)

What is happening

On an iOS simulator, inputText fails when the focused field is a secure text field, such as a password field using secureTextEntry. iOS shows a Strong Password suggestion over the field and text entry stops working, so the step fails.

This comes from iOS Password AutoFill, not from Maestro. Apple does not expose secure text fields to automation in a way that lets Maestro work around it.

Whether AutoFill is on by default depends on the iOS version of the simulator, so the same flow can pass on one simulator and fail on another.

Workaround

Use one of the following:

• Turn off AutoFill Passwords in the simulator. In the simulator, open Settings → Passwords → Password Options and turn off AutoFill Passwords. If the simulator asks for a password to open the Passwords settings, any text works. The exact menu path varies between iOS versions.

• Turn off AutoFill from the command line. This is useful on CI. Boot the simulator first, then run both of these, replacing <DEVICE_ID> with the simulator's UDID from xcrun simctl list devices:

  plutil -replace restrictedBool.allowPasswordAutoFill.value -bool NO \
    ~/Library/Developer/CoreSimulator/Devices/<DEVICE_ID>/data/Library/UserConfigurationProfiles/EffectiveUserSettings.plist
  plutil -replace restrictedBool.allowPasswordAutoFill.value -bool NO \
    ~/Library/Developer/CoreSimulator/Devices/<DEVICE_ID>/data/Containers/Shared/SystemGroup/systemgroup.com.apple.configurationprofiles/Library/ConfigurationProfiles/UserSettings.plist

  These files are internal to the simulator and Apple may change them, so this approach may stop working on newer iOS versions.

• Use a plain text field in test builds. Disable secureTextEntry on the password field when the app is built for testing. This is the most reliable option, but it means the test build differs from the release build.