Common Issues and FAQs

Platform.ready

Before using native Cordova plugins, apps need to listen for the platform ready event. The best way to do this is in the run function of your app: 

  myModule.run(function($ionicPlatform) {
    $ionicPlatform.ready(function() {
      // Anything native should go here, like StatusBar.styleLightContent()
    });
  });

Sometimes, this event never fires and that case can be difficult to debug. Generally, when $ionicPlatform.ready does not fire, or the lower-level deviceready event does not fire from Cordova, it means your plugins are in an inconsistent state.

To remedy this, remove your existing plugins and reinstall them. For each plugin, run: 

  ionic cordova plugin rm cordova-plugin-statusbar
  ionic cordova plugin add cordova-plugin-statusbar

If this does not resolve the issue, please let us know if you might be using a cordova plugin that is faulty: Report Bad Cordova Plugin

Unstable or outdated Cordova Plugin

Are you using a Cordova plugin that is either unstable (crashes, doens't function properly), or outdated (breaks on new mobile OS's, etc.)?

Let us know by reporting it on our Bad Cordova Plugin form.

We can't promise we'll be able to fix the issue, but we are working hard to improve the quality of the Cordova plugin community and your report helps. We aren't able to respond individually to cordova plugin issue reports at this time.

Ionic breaks touch/mouse events for 3rd party library

Running into an issue where Ionic's tap and event handling system is conflicting with a 3rd party library, such as a map widget or embedded object?

Ionic's complex event system makes it possible to build mobile apps in the browser with fast and fluid touch events and gestures. Unfortunately, that can conflict with widgets that expect to have full control over their own events.

To fix this, add data-tap-disabled="true" around the widget. For example: 

  <div id="google_map" data-tap-disabled="true"></div>

Ionic CLI

When working with Cordova and Ionic, Node is to be your best friend. Specifically, working with Node and the Command Line. Yet getting things set up often seems to be a challenge, especially when it comes to setting up things cross platform (Mac, Windows, Linux).

Below are a few issues that are not necessarily an Ionic Framework issue, but common pitfalls seen related to Cordova, Node, NPM, Android:

Android SDK

Setting up the Android SDK is a complicated process for Windows and Linux.

Recently, Ubuntu has gotten an awesome tool called Ubuntu Developer Tools Center and with it you can install the Android SDK and Android Studio. I’m not going to go over the details, but you can check out this blog post and see the steps.

The setup process for Android on Windows has been covered in depth on our YouTube tutorial. The only thing I can add is to include installing git during your setup.

Macs tend to have the least problems when setting up an Android environment. There a few ways to handle it and this is just one of them. The end goal is to have the SDK installed, install Java, install Ant.

Install Java - This can be by going to this page. Install Ant - The quickest way to install Apache Ant is with Homebrew.

 $ brew install ant

Install the SDK - This can be done a few different ways. The one I like to use is by installing Android Studio. This will let you install an editor that comes bundled with the Android SDK. So now our SDK is in our Applications Folder.

Edit .bash_profile - So if you’ve followed the steps above, you’ll need to edit your .bash_profile to include the following. If you didn’t install Android Studio, then no problem. You’ll just need to change the path to the SDK. You want to include the SDK tools and SDK Platform-tools.

 vim ~/.bash_profile

Add this:

export PATH=${PATH}:/Applications/Android\ Studio.app/sdk/platform-tools:/Applications/Android\ Studio.app/sdk/tools
export JAVA_HOME=$(/usr/libexec/java_home)
export PATH=${JAVA_HOME}/bin:$PATH
export PATH=/usr/local/bin:$PATH

With that, enter source ~/.bash_profile to update everything.

Faster Android Emulation

Having trouble emulating your Android apps? The Android emulator is notoriously slow, but there are some new choices available for speeding it up.

First, follow the Android Emulator docs to ensure you're tried an image with Intel virtualization extensions added.

If that doesn't work, Genymotion is a great replacement. It uses a virtual machine to emulate android devices and does it nearly perfectly. One thing to remember, if you want to deploy to a genymotion device, your computer will treat it as an actual connect machine. So instead of running

        $ ionic cordova emulate android

Use run instead.

        $ ionic cordova run android

Unreleased Node Versions

If you’re a node developer, you’re probably using the latest and greatest release of node on your system. While this is great for testing apps with node, Cordova and Ionic need to have some stability. When doing anything with the command line and Ionic, always use a stable release of node.

Starting the iOS Simulator

Starting an iOS emulator from the command line is a really powerful feature. It gets rid of the need to open up Xcode and keeps a nice terminal-only workflow. But when you try to use ionic cordova emulate ios it throws an awful error.

Error: ios-sim was not found. Please download, build and install version 1.7 or greater from https://github.com/phonegap/ios-sim into your path. Or 'npm install -g ios-sim'; using node.js: http://nodejs.org/

Well this is because you need to install a utility package called ios-sim. This package allows you to access the iOS simulator from the command line. This can be installed with a simple npm install.

$ sudo npm install -g ios-sim

With this installed, you’ll be able to emulate to the iOS-simulator.

Missing Plugins

When you update an iOS project to a new version of Cordova, sometimes you will get an error saying it was unable to locate a plugin. You open up Xcode, try to run and build from there and get this error in your console

  2014-11-12 14:36:18.284 Tell The DJ[14955:c07] ERROR: Plugin 'Device' not found, or is not a CDVPlugin. Check your plugin mapping in config.xml.
2013-08-23 14:36:18.284 Tell The DJ[14955:c07] -[CDVCommandQueue executePending] [Line 116] FAILED pluginJSON = [
  "Device1096677259",
  "Device",
  "getDeviceInfo",
  [

  ]
]

This can happen for a number of reasons, but the most common is manually adding files to the native project. The linking process during a build cycle gets broken and none of the native files are moved over. To fix this, delete the ios.json file in the plugins folder. This will make Cordova have to recopy all the plugin files.

In more extreme cases, sometimes a complete removal of the project is needed.

Cordova Directory

This one is pretty extreme and can cause a lot of frustration. You try to use any of the Cordova/Ionic commands and get this error.

          Current Working Directory is not Cordova-based project

At this point you’re unable to do anything further with your project. So why does this happen? Various reason, but mostly something gets corrupted with your environment configuration. You can see a thread where this happened for one particular user.

For his case, the solution was to run

          $ cordova create .

Basically a hidden folder that should be there wasn’t. Running that command above fixes that issue.

Cordova Updates

When Cordova pushes a new version, it’s always best to update. So you run this command to update the Cordova binaries.

$ sudo npm update -g cordova

Great, but when you try to do anything in a project, you’ll get an error. Well this is because there are actually different versions of Cordova for each platform. So from inside your project you need to run Cordova’s update command.

        $ ionic cordova platform update ios
        $ ionic cordova platform update android

Now all your platform specific versions of Cordova are updated.

Windows and Git

So you found this awesome plugin on github that you want to use for your app. So lets try to install it.

          ionic cordova plugin add http://github.com/user/awesome-plugin

But then another error comes up. Whats going on? So something that Cordova doesn’t mention is that you need to have git setup for installing plugins from Github. Something like this can easily be overlooked, but thankfully it’s as easy to fix. Just visit the git website, install and set up git, and you’re good to go.

Missing Cordova Hooks

If your project was created with an older version of the Ionic CLI, you may have come across this. You start to build as

          addCliHookDirectory fs.chmodSync: Error: ENOENT, no such file or directory 'hooks/after_prepare/010_add_platform_class.js'

Thankfully this has been fixed in the latest version of the Ionic CLI. If the hook isn't found when you try to build either iOS or Android, the Ionic CLI will add it back.

Incorrect Hook Permissions

If, instead, you see an error like this (as described in this Ionic Forum post):

  ionic cordova emulate ios
  running cordova emulate ios
  Running command: /Users/username/myApp/hooks/after_prepare/010_add_platform_class.js /Users/username/myApp
  Error: spawn EACCES

You should run 

  chmod -R +x hooks/after_prepare

This problem has been fixed in a recent version of the Ionic CLI but only helps new projects.