Troubleshooting NativeScript Android Setup Issues

NativeScript is one of the most compelling open source cross-platform development frameworks for building truly native mobile apps. If you are new to NativeScript, native mobile app development in particular, or mobile app development in general, it is important to set up your development environment quickly and efficiently.

As a developer, you will be very content with the experience that NativeScript provides to get your first hello world app up and running. All you have to do is to follow the instructions in the quick start guide. You would want to look at the Advanced Setup for OSX, Windows and Linux.

In this post I am going to present how I managed to solve the Android setup issues that I had when building a NativeScript application on a new machine. I will include the commands for OSX but you can find the equivalent for Windows. I am going to assume that:

  • You have installed the android SDK on your machine
  • You have created a new NativeScript project and added the android platform by using tns platform add android
  • You have attempted the run the project using tns run android –emulator and it failed
  • You got an error that is not related to your application’s code and which can be reproduced in a hello world app

ANDROID_HOME Environment Variable

Before you attempt to build your application for Android, the ANDROID_HOME environment variable must be set, and the SDK tool directories must be added to your path. You can open your command line and type:


This command should return the Android SDK’s root directory path

echo $PATH

This command should return the list of directories in the $PATH and it should include the Android Platform Tools directory.

If you don’t see the expected results, then you need to follow one of the guides to set the ANDROID_HOME environment variable.

Android APIs

Once your environment variable is set, you can execute the following command to open up the Android SDK Manager:

android sdk

Android SDK Manager

You need to make sure that you have at least one API level installed. You need to select the SDK Platform with at least one System Image that you are going to use. Android supports different processor architectures and x86 is known to run much faster in the Emulator (You will get such warning if you use the 64 image). Depending on the application that you are trying to build and which Android versions you are targeting, you may select and install more than one API level and System Image.

Android Virtual Devices

Now that we validated that you’ve installed at least one API level and Image, we can proceed with verifying that you have at least one Android Virtual Device. NativeScript requires the existance of that Virtual Device if you want to use the Android Emulator. You need to either use the Tools menu to Manage AVDs or run the following command

android avd

Android AVD

If you don’t have any AVDs, then you need to create a new one. You may notice that one or more AVDs have the warning badge. In most cases, it means that your system image is not found or one or more properties need to be changed.

Android Virtual Device Error

To verify that you have at least one virtual device, you can use the following command:

android list avd

Android Emulator

At this point, you can confirm that you have a working Android Virtual Device (AVD) which you can either by using the command line:

emulator -avd <name>

or by clicking on the AVD in the AVD Manager and then Start.

Run Emulator

The Android emulator should start, and your selected AVD should run.

Hardware Acceleration

When running the AVD using an Intel x86 System Image you might see the following message:

HAXM error

You will need to install the Intel Hardware Accelerated Execution Manager HAXM which allows for faster Android emulation. The OSX version can be downloaded from here. You can read more about it in this stackoverflow thread.

Wait, Where’s NativeScript?

You might be wondering where NativeScript really comes in. If you are having issues with the Android setup, then it is most likely not a NativeScript specific issue. Therefore you need to ensure that your Anrdroid Emulator can run the AVD before attempting to build any NativeScript applications.

However, the NativeScript CLI can certainly help in this matter by means of the tns doctor command. This command prints warnings about the current configuration and gives basic information about how to resolve them. For more information check out the Github repo page.

Genymotion For the Rescue

Genymotion can make the Android Setup less painful by eliminating a few steps. One of the common errors you might run into is this:

Genymotion error

Genymotion by default uses its own adb. If you have the Android SDK installed, you would want to switch to a custom adb and to select the location of the sdk:

Genymotion adb settings


The NativeScript CLI does a pretty good job when it comes to installing the tools and giving warning messages. Sometimes manual setup is required for an optimal configuration. These are only a few of the obstacles you might encounter along the way. Feel free to post any tips or findings in the comment box.


Leave a Reply

Your email address will not be published. Required fields are marked *