Understanding and Resolving net::ERR_CLEARTEXT_NOT_PERMITTED Errors After Upgrading to Cordova Android 8

Error Phenomenon and Background Analysis

After upgrading the Cordova Android platform to version 8.0, many developers encounter the net::ERR_CLEARTEXT_NOT_PERMITTED error, manifesting as the application's inability to connect to server targets using the http:// protocol. This error is not due to code logic issues but rather stems from changes in underlying security policies.

Evolution of Android Platform Security Policies

Cordova Android 8.0 raises the default API level to Android 9 (Pie). Starting from Android 9, the system introduces stricter security policies, with one significant change being the default prohibition of cleartext network communication by applications. This means all unencrypted HTTP requests are intercepted by the system, which is part of the evolution of Android's security architecture aimed at protecting user data from man-in-the-middle attacks.

Solution: Enabling Cleartext Communication

To restore HTTP connections in Cordova applications, cleartext communication must be explicitly enabled in AndroidManifest.xml. Cordova provides a mechanism to modify AndroidManifest.xml through the config.xml file. The core solution involves adding the following code to the Android platform configuration in config.xml:

<platform name="android">
  <edit-config file="app/src/main/AndroidManifest.xml" mode="merge" target="/manifest/application">
      <application android:usesCleartextTraffic="true" />
  </edit-config>
</platform>

This configuration uses the edit-config element to merge the android:usesCleartextTraffic="true" attribute into the application tag of the generated AndroidManifest.xml file, thereby overriding the system's default security policy.

XML Namespace Handling

During actual configuration, developers may encounter an error: unbound prefix build error. This occurs because the android:usesCleartextTraffic attribute uses the Android XML namespace, which is not defined in config.xml. The solution is to ensure that the widget tag includes the necessary namespace declarations:

<widget id="your-app-id" version="1.2.3"
xmlns="http://www.w3.org/ns/widgets" 
xmlns:android="http://schemas.android.com/apk/res/android"
xmlns:cdv="http://cordova.apache.org/ns/1.0">

Here, xmlns:android="http://schemas.android.com/apk/res/android" defines the Android namespace, allowing the android: prefix to be correctly parsed. This is a fundamental requirement for XML document structural integrity and a technical detail often overlooked by developers.

Security Considerations and Best Practices

While enabling cleartext communication resolves connection issues, developers must recognize that this reduces application security. Where possible, it is recommended to upgrade servers to HTTPS protocols to align with modern cybersecurity standards. If HTTP must be used, ensure the communication environment is relatively secure and consider implementing application-level encryption as supplementary protection.

Debugging and Verification

After configuration, it is advisable to perform the following verification steps: first run cordova platform rm android to remove the Android platform, then run cordova platform add android@8.x.x to re-add the platform, and finally build and test the application. Use Android Studio's Logcat tool to monitor network requests and confirm whether the net::ERR_CLEARTEXT_NOT_PERMITTED error has disappeared.

Technical Impact Analysis

The emergence of this issue reflects the trend of continuously improving security standards in the mobile development ecosystem. As a cross-platform framework, Cordova must balance backward compatibility with new platform features. Developers should pay attention to change logs for each major version upgrade, especially those involving security policies and API level changes, to prepare for adaptation in advance.