Troubleshooting tips for the Surface Duo emulator

Please visit the Surface Duo Tech Community to ask questions or discuss any issues you are having with the Surface Duo emulator or SDK.

Following are some common issues and their resolution.

Android 12L emulator does not start

The latest Surface Duo Android 12L emulator requires the Android Emulator in your SDK tools to be version 31.3.12 or newer (or 32.1.5 or newer in the canary channel).

Check the pre-requisites, download, and installation steps for detailed instructions on how to update your emulator in the SDK tools.

Android 11 emulator does not start

You might see the following error in the terminal output:

WARNING | Failed to process .ini file Surface_Duo_2_API_32.avd/config.ini for reading.
ERROR   | bad config: virtual device file has no valid path.rel entry nor path entry

This error indicates a configuration mismatch between the Surface Duo emulator and the emulator in SDK tools. In Android Studio you go to Tools > SDK Manager > SDK Tools tab to see the current version (and whether any upgrades are available). If you have version 31.3.12 or newer (or 32.1.5 or newer in the canary channel) then you will need to update an INI file to restore compatibility between the Surface Duo Android 11 emulator and the Android SDK version:

1. Go to the path ..\SurfaceDuoEmulator_<version>\artifacts\.android\avd\
2. Edit the file Surface_Duo_2_API_32.ini,
3. Change parameter path.rel to Surface_Duo_2_API_32.avd (for older emulators, it was historically set to avd\Surface_Duo_2_API_32.avd)
4. Save and retry starting the emulator.

Android 11 emulator does not finish booting

If the Surface Duo emulator gets stuck showing a black screen while booting, this can indicate the emulator is having trouble loading data or state from a previous execution. To resolve this issue close the emulator and re-start it by using a wipe script to start the emulator. Scripts are located in the Surface Duo 2 emulator image install location.

If you understand and agree to wipe all user data, use ./run_wipe_SurfaceDuo2.bat on Windows, or ./run_wipe_SurfaceDuo2.sh on macOS and Linux.

An alternative solution is to install your new emulator in a different file location than a previously installed Surface Duo Android emulator. You can choose the install location as part of the installation process.

Surface Duo emulator does not appear in the device list in Android Studio or Visual Studio

The current version of the Surface Duo emulator cannot be started by your IDE. First manually start the emulator and once it's running it should appear in the list for deployment and debugging:

• Windows - choose from Start > Surface Duo Emulator.
• Mac - start from the command line using ./run_SurfaceDuo2.sh (or ./run_vs_SurfaceDuo2.sh for Visual Studio for Mac).

Once you have started the Surface Duo emulator, it should appear in the device list as Virtual device.

Surface Duo emulator does not appear in the Android Virtual Device (AVD) Manager

The current version of the Surface Duo emulator cannot be managed in AVD Manager. Instead it must be installed from our download page and started manually:

• Windows - choose from Start > Surface Duo Emulator or the desktop icons if they are available.
• Mac - start from the command line using ./run_SurfaceDuo2.sh (or ./run_vs_SurfaceDuo2.sh for Visual Studio for Mac).

Apps do not open across both screens

By default applications will only open on a single screen. The user can then choose to span the application across both screens by dragging the handle at the bottom of the app window:

Customers can opt-in to apps opening across both screens by default in Settings. To auto-span apps, go to Surface Duo features > Span apps automatically and turn on the switch. Once the feature is enabled, individual apps can be set to auto-span from the list. Apps will only open on both screens if the screens are empty, otherwise the app will open only on the screen where it was activated.

This feature in available on Android 11 and newer.

Contents do not rotate with the emulator

Verify that Auto-rotate is enabled in the notification drawer or in Settings > Display > Auto-rotate screen.

How to "Factory reset" the Surface Duo emulator

In the installation folder, there are batch files with wipe in the filename. When you start the emulator with one of the scripts, it will effectively "factory reset" the emulator.

• Windows - In the artifacts folder inside of the installation folder, you can execute run_wipe_SurfaceDuo2.bat (or run_vs_wipe_SurfaceDuo2.bat for Visual Studio) directly to return the Surface Duo emulator image to its original state.
• Mac - In a terminal window, navigate to the folder where you copied the emulator files. And then type ./run_wipe_SurfaceDuo2.sh (or ./run_vs_wipe_SurfaceDuo2.sh for Visual Studio for Mac) to return the Surface Duo emulator image to its original state.

These files are installed with the emulator version 2020.1014.2 released in mid-October 2020.

If you are using an older version and cannot update immediately

If you have an earlier version, you should download the latest version, or you can create a script file manually. Start by copying the existing run_clean (or run_vs_clean) file to run_wipe (or run_vs_wipe) and modify it as shown below:

@echo off
set DIRNAME=%~dp0
if "%DIRNAME%" == "" set DIRNAME=.\
"%DIRNAME%\run.bat" -wipe-data

or for shell files on macOS and Linux:

#!/bin/sh
./run.sh -wipe-data

The updated batch/script file should be located in the same directory as the existing batch/script files that you use to start the emulator. If you are modifying the Visual Studio version (with _vs in the filename) be sure the final line refers to run_vs.bat or run_vs.sh.

Surface Duo emulator fails to launch after an interruption

When the emulator is interrupted while in the middle of saving a Snapshot, on subsequent launches, it will attempt to boot from a corrupted snapshot state. Or, sometimes an unexpected issue happens while the emulator is running, and attempts to launch it result in the error, "emulator: ERROR: bad workspace: cannot find prebuilt kernel in: ../bin/prebuilts/qemu-kernel/x86_64/kernel-qemu"

In this case, perform a Factory reset as described above to fix the issue and re-launch the emulator.