How to Fix NET::ERR_CLEARTEXT_NOT_PERMITTED (Android OS)
Quick Answer
The NET::ERR_CLEARTEXT_NOT_PERMITTED error indicates that an Android application is attempting to connect to a server using unencrypted HTTP (cleartext) when the system or application security policy requires HTTPS (encrypted) connections. The fastest fix often involves modifying the application's network security configuration to allow cleartext traffic for specific domains or temporarily for debugging purposes.
What Causes This Error
- Android 9 (API level 28) and higher block cleartext HTTP traffic by default for security reasons.
- The application's `AndroidManifest.xml` file explicitly sets `android:usesCleartextTraffic="false"` or targets API level 28+ without a specific network security configuration.
- A custom Network Security Configuration (NSC) within the application disallows cleartext traffic globally or for the specific domain.
- The server or API endpoint being accessed only supports HTTP, not HTTPS.
- An outdated or misconfigured third-party library within the application attempts cleartext connections.
Step-by-Step Fixes
1Modify AndroidManifest.xml to Allow Cleartext Traffic (Application-Wide)
- Open your Android project in Android Studio.
- Navigate to the `app/src/main` directory and open the `AndroidManifest.xml` file.
- Locate the `<application>` tag.
- Add or modify the `android:usesCleartextTraffic` attribute within the `<application>` tag to `android:usesCleartextTraffic="true"`. For example: `<application android:usesCleartextTraffic="true" ...>`. This permits cleartext traffic for all domains accessed by the application.
- Rebuild and reinstall your application to apply the changes.
2Implement a Network Security Configuration (NSC) for Specific Domains
- Open your Android project in Android Studio.
- Create an XML file named `network_security_config.xml` in the `res/xml` directory. If the `xml` directory does not exist, create it.
- Add the following content to `network_security_config.xml`, replacing `your-domain.com` with the actual domain that requires cleartext: `<network-security-config><domain-config cleartextTrafficPermitted="true"><domain includeSubdomains="true">your-domain.com</domain></domain-config></network-security-config>`. This allows cleartext only for the specified domain and its subdomains.
- Open your `AndroidManifest.xml` file and add the `android:networkSecurityConfig` attribute to the `<application>` tag, pointing to the newly created configuration file. For example: `<application android:networkSecurityConfig="@xml/network_security_config" ...>`. Ensure `android:usesCleartextTraffic` is not set to `false` in the manifest, as the NSC will take precedence.
- Rebuild and reinstall your application to apply the changes.
3Verify Server Support for HTTPS
- Identify the URL or domain that is causing the NET::ERR_CLEARTEXT_NOT_PERMITTED error.
- Attempt to access the identified domain using HTTPS in a web browser (e.g., `https://your-domain.com`).
- If the HTTPS connection fails or results in a certificate error, it indicates that the server may not be properly configured for HTTPS or does not support it.
- Contact the server administrator or API provider to inquire about HTTPS support and configuration. Request that HTTPS be enabled or properly configured for production environments.
- If HTTPS is not an option, consider the Network Security Configuration approach for specific domains as a temporary measure, but prioritize secure connections.
4Update or Replace Outdated Libraries
- Review your application's `build.gradle` (module-level) file for any third-party libraries that handle network requests (e.g., OkHttp, Retrofit, Volley).
- Check the official documentation or release notes for these libraries to determine their latest stable versions and any known issues related to cleartext traffic.
- Update the library versions in your `build.gradle` file to the latest compatible versions. For example, change `implementation 'com.squareup.okhttp3:okhttp:3.x.x'` to `implementation 'com.squareup.okhttp3:okhttp:4.x.x'` (if applicable).
- Synchronize your Gradle project and rebuild the application.
- Test the application to see if the error persists. If the issue was due to an outdated library's default cleartext behavior, updating it may resolve the problem by leveraging newer security practices.
Frequently Asked Questions
What does 'Cleartext HTTP traffic not permitted' mean?
This error means that your Android application is trying to send or receive data over an unencrypted HTTP connection, but the Android operating system or the app's security policy is blocking it. Android 9 (API level 28) and higher prioritize secure (HTTPS) connections by default.
Is it safe to allow cleartext traffic?
Allowing cleartext HTTP traffic is generally not recommended for production applications, especially when transmitting sensitive data. Unencrypted connections are vulnerable to eavesdropping and tampering. It should only be used for debugging, testing, or when connecting to internal, non-sensitive endpoints where HTTPS is not feasible, and the risks are understood and accepted.
What is the difference between `android:usesCleartextTraffic` and Network Security Configuration?
`android:usesCleartextTraffic` is a manifest attribute that enables or disables cleartext traffic for the entire application. A Network Security Configuration (NSC) provides more granular control, allowing you to specify cleartext permissions for individual domains or apply different security rules based on the connection type, overriding the manifest setting if more restrictive.
Will this error occur on older Android versions?
The `NET::ERR_CLEARTEXT_NOT_PERMITTED` error specifically relates to the default cleartext traffic blocking introduced in Android 9 (API level 28). Applications running on older Android versions (pre-Android 9) will not encounter this error unless their `AndroidManifest.xml` or Network Security Configuration explicitly disallows cleartext traffic.
How can I debug which specific URL is causing the cleartext error?
You can use Android's Logcat to monitor network requests. Look for messages related to network security or `Cleartext HTTP traffic to [domain] not permitted` which will often include the specific domain or URL that is being blocked. Additionally, network proxy tools like Charles Proxy or Fiddler can intercept and display network traffic, helping to identify the problematic endpoints.