java.io.IOException: Cleartext HTTP traffic to [host] not permitted means Android denied an unencrypted http:// request under the app’s effective network security policy. This most commonly affects Android 9 or later when the app targets API level 28 or higher, including requests made through platform HTTP components and Media3 or ExoPlayer. The safest first action is to identify the exact blocked host or redirect source and move that request to HTTPS if the endpoint supports it; do not enable cleartext traffic globally before finding the destination.

What “Cleartext HTTP Traffic Not Permitted” Means

The same policy failure can appear as java.io.IOException: Cleartext HTTP traffic to [host] not permitted, CLEARTEXT communication to [host] not permitted by network security policy, or the shorter Cleartext HTTP traffic not permitted. Media3 can report the related ERROR_CODE_IO_CLEARTEXT_NOT_PERMITTED or CleartextNotPermittedException.

These signatures mean the app attempted an unencrypted HTTP connection and its effective policy refused the request. Android’s Android Network Security Configuration documentation states that cleartext support defaults to disabled for apps targeting API level 28 or higher. The target API level matters; the physical device running Android 9 or later does not, by itself, prove how every app’s policy is configured.

This guide applies when a direct URL, redirect, backend response, media playlist, CDN resource, platform component, or third-party SDK resolves to HTTP. It does not apply to SSLHandshakeException, CertPathValidatorException, or android.os.NetworkOnMainThreadException, which represent different failure conditions.

Find the HTTP Endpoint Android Is Blocking

Find the runtime destination before changing the application policy. The URL visible in application source may not be the URL Android ultimately blocks.

  1. Record the host shown in the exception or Logcat output.
  2. Check whether the original request URL begins with http://.
  3. Check whether an initial HTTPS request redirects to HTTP.
  4. Check whether a backend response, media playlist, or CDN supplies an HTTP resource URL.
  5. Use the stack trace to identify whether the request came from a platform component, Media3 or ExoPlayer, WebView, or a third-party library or SDK.

Media playback can fail even when the initial media URL appears correct because a playlist or referenced resource resolves to HTTP. Google’s Media3 cleartext troubleshooting identifies an HTTP URL under a policy that prohibits cleartext as the basis of this error family.

Direct HTTP URLs, redirects to HTTP, and HTTP resources returned by a backend all require the same first decision: determine whether that exact destination can use HTTPS. Do not create a domain exception until the actual runtime host is known.

Fix 1: Migrate the Failing Request to HTTPS

When this applies: Use this fix when you control the server or media endpoint, or can change the URL source, and HTTPS is available for the resource.

Prerequisites:

  • You control the endpoint or can change the source that supplies its URL.
  • The resource is available over HTTPS.
  1. Change the URL source from http:// to https://.
  2. Update redirects so they stay on HTTPS.
  3. Retest the exact failing request or playback path.

Expected result: If every resource in the tested path remains on HTTPS, Android should no longer deny that operation as cleartext traffic. A downstream redirect, playlist entry, or backend-supplied HTTP URL can still trigger the error and must be checked separately.

Risk and rollback: This is a low-risk configuration change with no expected data-loss action. Restore the previous URL only if the HTTPS rollout fails. Do not expand this step into unrelated certificate troubleshooting; certificate validation failures are outside this error’s scope.

Verify the Merged Manifest and Packaged Network Security Policy

When this applies: Use this confirmed diagnostic fix when the source manifest or Network Security Configuration appears correct but the runtime build still blocks the request.

Prerequisite: You must be able to inspect the merged manifest or packaged resources for the affected build.

  1. Check the merged manifest, not only the source XML.
  2. Confirm the packaged network_security_config.xml is present.
  3. Verify that the request host matches the allowed domain exactly.
  4. Check whether a redirect or playlist points to HTTP.
  5. Retest on the target build variant.

Expected result: Inspection should reveal whether the built application contains the intended android:networkSecurityConfig reference and packaged policy, and whether that policy covers the actual blocked host. It may also show that a different build variant or downstream HTTP resource is involved.

Risk and rollback: This is a low-risk inspection process with no data-loss risk and no rollback requirement. Do not assume a source-file change is active until the merged and packaged output has been checked.

Fix 2: Allow Cleartext Only for the Required Domain

When this applies: Use a domain-specific exception only when HTTP is unavoidable and you have identified the exact destination that requires it.

Prerequisites:

  • The app targets API level 24 or higher.
  • You can identify the exact host or subdomain.
  • You accept that cleartext HTTP can expose transmitted data to interception or modification.
  1. Add a Network Security Configuration XML.
  2. Set a domain-config with cleartextTrafficPermitted="true" for only the required host.
  3. Keep includeSubdomains false unless every subdomain genuinely requires HTTP.
  4. Reference the XML through android:networkSecurityConfig.
  5. Retest the blocked endpoint.

Expected result: The specified destination may be permitted to use HTTP while unrelated destinations remain subject to the app’s cleartext restrictions. Success depends on the configured domain matching the actual runtime host, including any redirect or media-resource destination.

Risk and rollback: This is a medium-risk security change with no expected data-loss action. Cleartext traffic remains vulnerable even when the destination is trusted. Remove the domain-config or migrate the endpoint to HTTPS to roll back the exception. Do not widen the configuration to unrelated domains or enable includeSubdomains merely to make a request pass.

API-Level Behavior and the android:usesCleartextTraffic Fallback

For the relevant target range, API level 28 and later defaults cleartext traffic to blocked. Network Security Configuration provides cleartext policy control from API level 24 onward. For API level 23 and below, the supplied Android version guidance requires android:usesCleartextTraffic in addition to a network-configuration strategy.

A Network Security Configuration can override android:usesCleartextTraffic on Android N and later. More importantly, the official usesCleartextTraffic application attribute documentation states that the attribute is ignored for apps targeting API level 38 and higher. It is therefore not a forward-compatible replacement for Network Security Configuration.

When the broad fallback applies: Use android:usesCleartextTraffic="true" only for temporary compatibility or when all cleartext traffic must be allowed in an older target range and no narrower domain option is currently available.

Prerequisites:

  • You understand that this setting broadly weakens transport security.
  • You have no narrower domain-specific option yet.
  1. Set android:usesCleartextTraffic="true" on the application element.
  2. Verify the merged manifest in the built APK or AAB.
  3. Confirm that the app still blocks unintended destinations if a network configuration is also present.
  4. Plan migration to Network Security Configuration or HTTPS.

Expected result: In target ranges where the attribute is honored, the application may be allowed to make cleartext requests unless an effective Network Security Configuration imposes different behavior. It will not provide this fallback for apps targeting API level 38 or higher.

Risk and rollback: This is a high-risk security fallback because it can allow cleartext traffic across the application. It does not erase application data, but it can expose transmitted data to interception or modification. Set the attribute back to false and remove the HTTP dependencies to roll it back.

Check Localhost, 10.0.2.2, Numeric IPs, Redirects and Media URLs

Local development and generated resource URLs require app-specific verification. If the destination is localhost, a loopback address, 10.0.2.2, or a numeric IP, confirm the actual runtime host and intended build environment before changing policy. Reports involving these destinations are useful diagnostic signals, but they do not establish how a particular app’s configuration will match its host.

  • Confirm whether the destination is development-only.
  • Check whether the same cleartext policy is unintentionally packaged in a release build.
  • Inspect redirects, media playlists, CDN resources, and backend-supplied URLs for HTTP destinations.
  • Identify whether HttpURLConnection, OkHttp, WebView, MediaPlayer, DownloadManager, Media3, ExoPlayer, or a third-party SDK emitted the error before drawing component-specific conclusions.
  • Manually test the affected host and build variant rather than assuming a domain exception matches every local or numeric destination.

Do not enable application-wide cleartext traffic for production merely to accommodate a development server. If HTTP is temporarily unavoidable, keep any confirmed exception limited to the required destination and verify that it is not broader than intended.

Confirm the Exact Error Is Resolved Without Broadening Cleartext Access

  1. Retest the exact request, redirect chain, or playback path that originally produced the error.
  2. Test the affected target build variant rather than assuming one variant represents every build.
  3. Recheck the merged manifest and packaged Network Security Configuration after making a policy change.
  4. If a domain exception was used, confirm that only the required destination is permitted and unrelated HTTP destinations remain blocked.
  5. Record whether the build targets API level 28 or higher and API level 38 or higher before interpreting manifest behavior.

The original operation should complete without the cleartext-denial signature, while the application retains the narrowest possible policy. A source-file edit alone does not confirm resolution. If the error remains, recheck the runtime host, redirect chain, playlist resources, packaged configuration, and originating library rather than widening the exception.