Troubleshooting

Here are some of the common things which go wrong when you bring your project to VoltBuilder. Many of these are due to changes in the underlying requirements for Android, iOS or Cordova, not caused by VoltBuilder itself.

• Remote Debugging
• Obsolete use of config-file in config.xml
• UIWebView
• Permissions
• CORS error and white screen on startup
• AndroidX
• HTTP Requests not working
• Incorrect androidAlias or androidAliasPassword
• Apps not appearing on routing list
• Cordova not found (runtime)

If you can’t find your answer, get Support.

Remote Debugging

If your app fails at runtime, the next step is to open a remote debugging session to debug your app. You’ll be able to see if there are error messages on the Console.

For Android, use Chrome Remote Debugging.

For iOS, use Safari Remote Debugging (MacOS only) or Inspect.dev (Windows or MacOS).

If you want to look at the console at runtime without connecting a remote browser, use the cordova-console.log library. It hijacks the output of console.log() sending it into a div in your app. You can then view it on your device.

Another ($) option is BrowserStack

Obsolete use of config-file in config.xml.

Up to cli-7.0.1, PhoneGap allowed this type of clause: UIWebView

<config-file platform="ios" parent="SomeXMLElement" mode="replace">
  <SomeXMLElement someAttribute="text" >Go Skiing</SomeXMLElement>
</config-file>

Apache Cordova started using the same <config-file command for its plugins, which conflicted with the PhoneGap implementation. PhoneGap then changed to use Cordova’s edit-config. You’ll need to change these in your config.xml. Consult the documentation for the affected controls to get the details.

Example 1: Change this:

<config-file parent="UIStatusBarHidden" platform="ios" target="*-Info.plist">
    <true/>
</config-file>

to this:

<edit-config file="*-Info.plist" mode="merge" target="UIStatusBarHidden">
    <true/>
</edit-config>

Example 2: Change this:

<config-file platform="android" parent="/manifest" mode="merge">
  <supports-screens android:anyDensity="true" android:resizeable="true"
    android:smallScreens="true" android:normalScreens="true" android:largeScreens="true"
    android:xlargeScreens="true" />
</config-file>

to this:

<edit-config file="AndroidManifest.xml" target="/manifest/supports-screens" mode="merge">
  <supports-screens android:anyDensity="true" android:resizeable="true"
    android:smallScreens="true" android:normalScreens="true" android:largeScreens="true"
    android:xlargeScreens="true" />
</edit-config>

Example 3: Change this:

<gap:config-file overwrite="true" parent="NSLocationAlwaysUsageDescription" platform="ios">
    <string>This app needs access to your location to determine your pickup point</string>
</gap:config-file>

to this:

<edit-config target="NSLocationAlwaysUsageDescription" file="*-Info.plist" mode="merge">
    <string>This app needs access to your location to determine your pickup point</string>
</edit-config>

Example 4: Change this:

<gap:config-file overwrite="true" parent="NSLocationWhenInUseUsageDescription" platform="ios">
    <string>This app needs access to your location to determine your pickup point</string>
</gap:config-file>

to this:

<edit-config target="NSLocationWhenInUseUsageDescription" file="*-Info.plist" mode="overwrite">
    <string>Allow the app to know your location</string>
</edit-config>

Example 5: Change this:

<config-file platform="winphone" parent="/Deployment" mode="replace">
  <DefaultLanguage xmlns="" code="da-DK"/>
  <Languages xmlns="">
    <Language code="da-DK"/>
    <Language code="en-US"/>
  </Languages>
</config-file>

to nothing. “winphone” is no longer supported.

UIWebView

iOS has dropped support for UIWebView. If your config.xml file includes the UIWebView plugin, you’ll get an error. Remove it, and replace with this:

<platform name="ios">
    <preference name="WKWebViewOnly" value="true" />

    <feature name="CDVWKWebViewEngine">
        <param name="ios-package" value="CDVWKWebViewEngine" />
    </feature>

    <preference name="CordovaWebViewEngine" value="CDVWKWebViewEngine" />
</platform>

There is more information in the Apache Cordova docs. You may not actually have UIWebView in your config.xml file - but it could be used by other plugins. In that case, you’ll need to update the other plugins.

Permissions

If you are using the location, camera or photo album, iOS requires you to ask the user for permission first. You can change the wording: for example, to use a different language. Declare these in your config.xml file as follows:

<platform name="ios">
  <edit-config target="NSLocationAlwaysUsageDescription" file="*-Info.plist" mode="overwrite">
    <string>Allow the app to know your location</string>
  </edit-config>
  <edit-config target="NSLocationWhenInUseUsageDescription" file="*-Info.plist" mode="overwrite">
    <string>Allow the app to know your location</string>
  </edit-config>
  <edit-config target="NSCameraUsageDescription" file="*-Info.plist" mode="overwrite">
    <string>App would like to access Camera to take picture of any document that you want to upload as attachment to your message</string>
  </edit-config>
  <edit-config target="NSPhotoLibraryUsageDescription" file="*-Info.plist" mode="overwrite">
    <string>Allow the app to open Photo Library to take picture of any document that you want to upload as attachment to your message</string>
  </edit-config>
</platform>

CORS error and white screen on startup

If your app has a white screen on startup, you probably have an error in your code which stops it from running. To see the error, check out Remote Debugging (at the bottom).

The most common reason is Content Security Policy (CSP) errors. Both Android and iOS require apps only access URLs which are known and secure. The CSP sets those rules. Here’s a very simple CSP - put this in your index.html file:

<meta http-equiv="Content-Security-Policy" content="default-src 'self' ">

(You’ll want to make this more restrictive, so that only the files you actually need are authorized)

Errors messages you might see include Cross origin requests are only supported for HTTP and XMLHttpRequest cannot load ... due to access control checks.

You may also need to add lines to your config.xml file:

    <!-- To allow connections to other resources, you must explicitly permit them using `access` tags. -->
    <!-- https://s.apache.org/cdv-network-request-access -->
    <!-- Example:
    <access allow="https://cordova.apache.org" />
    -->

    <!-- To control which URLs the WebView itself can be navigated to, use the `allow-navigation` tags. -->
    <!-- https://s.apache.org/cdv-allow-navigation -->
    <!-- Example:
    <allow-navigation href="https://cordova.apache.org/*" />
    -->

    <!-- To control which URLs the app is allowed to ask the system to open, use the `allow-intent` tags. -->
    <!-- https://s.apache.org/cdv-allow-intent -->
    <allow-intent href="http://*/*" />
    <allow-intent href="https://*/*" />

AndroidX

If your project uses AndroidX dependancies, AndroidX needs to be enabled. Add this to your config.xml:

<preference name="AndroidXEnabled" value="true" />

AndroidX is the replacement for the Android Support Library, which is no longer maintained. Many plugins used ASL - hopefully the plugins you use have been updated to use AndroidX.

You may also see a message like this: error: package android.support.v4.content does not exist. If you get this, you are using a plugin which has not been updated. Check npmjs.com for updates. You can also add this plugin, which allows older plugins to be used in AndroidX projects:

<plugin name="cordova-plugin-androidx-adapter" />

HTTP Requests not working

Both Android and iOS have started enforcing TLS and CORS/CSP.

From Android 9 Pie onwards, requests without encryption will not work, and by default, Android expects you to use TLS.

The easy way to bypass this is to add this plugin to your config.xml

<plugin name="cordova-plugin-cleartext" />

Although you should try to make your requests through the secure https protocol.

Incorrect androidAlias or androidAliasPassword

When your Android certificate is created, it will have an Alias and a Password for that alias. You need to put that information in your voltbuilder.json file for your app to be signed.

If you used VoltSigner to create your certificate, androidAlias is always set to key0. androidAliasPassword is set to the same password as the certificate.

If you do not have the information about your alias, you can use the following command to get the information from your .p12 file: openssl pkcs12 -info -in yourcert.p12

The openssl command is available on MacOS, and can be downloaded for Windows here.

There are certain lines in the output you want to identify:

Bag Attributes
    friendlyName: key0
    localKeyID: FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF

The friendlyName is the androidAlias. You’ll need to type in two passwords. The second “PEM pass phrase” is your androidAliasPassword.

Apps not appearing on routing list

(Applicable to Android 11+)

If your app calls other apps at runtime, using a plugin like cordova-plugin-app-launcher, you need to declare the other apps in your config.xml. You can do so by adding this code:

    <config-file target="AndroidManifest.xml" parent="/manifest">
      <queries>
          <package android:name="com.voltbuilder.test" />
          <package android:name="com.whatsapp" />
      </queries>
    </config-file>

More information here.

Cordova not found (runtime)

If your project builds properly, but does not work properly at runtime, use Remote Debugging to see if any errors are thrown.

If you see Cordova not found on the Console, there are a couple of possibilities:

• Your index.html file does not have this statement:

<script src="cordova.js"></script>

• There is a problem with a plugin. No error was detected in the build, so VoltBuilder thinks the build was successful. To isolate which plugin is the cause, look through the log for warnings or other messages. You should also check to make sure all your plugins are up to date.