java.io.IOException: Cleartext HTTP traffic to [host] not permitted significa que o Android recusou uma solicitação http:// não criptografada de acordo com a política de segurança de rede efetiva do app. Isso afeta com mais frequência o Android 9 ou posterior quando o app é destinado ao nível 28 ou superior da API, incluindo solicitações feitas por componentes HTTP da plataforma e pelo Media3 ou ExoPlayer. A primeira medida mais segura é identificar o host exato bloqueado ou a origem do redirecionamento e migrar essa solicitação para HTTPS caso o endpoint ofereça suporte; não permita tráfego não criptografado globalmente antes de localizar o destino.

O que significa “Cleartext HTTP Traffic Not Permitted”

A mesma falha de política pode aparecer como java.io.IOException: Cleartext HTTP traffic to [host] not permitted, CLEARTEXT communication to [host] not permitted by network security policy ou a forma abreviada Cleartext HTTP traffic not permitted. O Media3 também pode informar o código relacionado ERROR_CODE_IO_CLEARTEXT_NOT_PERMITTED ou a exceção CleartextNotPermittedException.

Essas assinaturas indicam que o app tentou estabelecer uma conexão HTTP não criptografada e que sua política efetiva recusou a solicitação. A documentação da Configuração de segurança de rede do Android informa que o suporte a tráfego não criptografado fica desativado por padrão em apps destinados ao nível 28 ou superior da API. O nível da API de destino é relevante; o simples fato de o dispositivo físico executar o Android 9 ou posterior não comprova como a política de cada app está configurada.

Este guia se aplica quando uma URL direta, um redirecionamento, uma resposta do backend, uma playlist de mídia, um recurso de CDN, um componente da plataforma ou um SDK de terceiros resolve para HTTP. Ele não se aplica a SSLHandshakeException, CertPathValidatorException ou android.os.NetworkOnMainThreadException, que representam condições de falha diferentes.

Encontre o endpoint HTTP que o Android está bloqueando

Identifique o destino em tempo de execução antes de alterar a política do aplicativo. A URL visível no código-fonte pode não ser a URL que o Android bloqueia ao final.

  1. Anote o host exibido na exceção ou na saída do Logcat.
  2. Verifique se a URL original da solicitação começa com http://.
  3. Verifique se uma solicitação HTTPS inicial redireciona para HTTP.
  4. Verifique se uma resposta do backend, playlist de mídia ou CDN fornece uma URL de recurso HTTP.
  5. Use o rastreamento de pilha para identificar se a solicitação veio de um componente da plataforma, do Media3 ou ExoPlayer, do WebView ou de uma biblioteca ou um SDK de terceiros.

A reprodução de mídia pode falhar mesmo quando a URL inicial parece correta, pois uma playlist ou um recurso referenciado pode resolver para HTTP. A documentação de solução de problemas de tráfego não criptografado do Media3 identifica uma URL HTTP usada sob uma política que proíbe esse tráfego como a causa dessa família de erros.

URLs HTTP diretas, redirecionamentos para HTTP e recursos HTTP retornados por um backend exigem a mesma decisão inicial: determinar se o destino exato pode usar HTTPS. Não crie uma exceção de domínio até conhecer o host realmente usado em tempo de execução.

Correção 1: migre a solicitação com falha para HTTPS

Quando se aplica: use esta correção quando você controla o servidor ou endpoint de mídia, ou pode alterar a origem da URL, e o recurso está disponível por HTTPS.

Pré-requisitos:

  • Você controla o endpoint ou pode alterar a origem que fornece a URL.
  • O recurso está disponível por HTTPS.
  1. Altere a origem da URL de http:// para https://.
  2. Atualize os redirecionamentos para que permaneçam em HTTPS.
  3. Teste novamente a solicitação exata ou o fluxo de reprodução que falhou.

Resultado esperado: se todos os recursos do fluxo testado permanecerem em HTTPS, o Android não deverá mais recusar a operação como tráfego não criptografado. Um redirecionamento posterior, uma entrada de playlist ou uma URL HTTP fornecida pelo backend ainda poderá acionar o erro e deverá ser verificada separadamente.

Risco e reversão: esta é uma alteração de configuração de baixo risco, sem expectativa de perda de dados. Restaure a URL anterior somente se a implantação de HTTPS falhar. Não amplie esta etapa para solucionar problemas de certificado não relacionados; falhas de validação de certificado estão fora do escopo deste erro.

Verifique o manifesto mesclado e a política de segurança de rede empacotada

Quando se aplica: use esta correção de diagnóstico confirmada quando o manifesto de origem ou a Configuração de segurança de rede parecer correto, mas o build em execução ainda bloquear a solicitação.

Pré-requisito: você precisa conseguir inspecionar o manifesto mesclado ou os recursos empacotados do build afetado.

  1. Verifique o manifesto mesclado, não apenas o XML de origem.
  2. Confirme se o arquivo network_security_config.xml está presente no pacote.
  3. Verifique se o host da solicitação corresponde exatamente ao domínio permitido.
  4. Verifique se um redirecionamento ou uma playlist aponta para HTTP.
  5. Teste novamente na variante de build de destino.

Resultado esperado: a inspeção deve revelar se o aplicativo compilado contém a referência android:networkSecurityConfig e a política empacotada pretendidas, além de mostrar se essa política abrange o host realmente bloqueado. Ela também pode indicar o envolvimento de outra variante de build ou de um recurso HTTP posterior.

Risco e reversão: este é um processo de inspeção de baixo risco, sem risco de perda de dados e sem necessidade de reversão. Não presuma que uma alteração no arquivo-fonte está ativa antes de verificar as saídas mescladas e empacotadas.

Correção 2: permita tráfego não criptografado somente para o domínio necessário

Quando se aplica: use uma exceção específica por domínio somente quando HTTP for inevitável e você tiver identificado o destino exato que exige esse protocolo.

Pré-requisitos:

  • O app é destinado ao nível 24 ou superior da API.
  • Você consegue identificar o host ou subdomínio exato.
  • Você aceita que o HTTP não criptografado pode expor os dados transmitidos à interceptação ou modificação.
  1. Adicione um XML de Configuração de segurança de rede.
  2. Defina um domain-config com cleartextTrafficPermitted="true" somente para o host necessário.
  3. Mantenha includeSubdomains como falso, a menos que todos os subdomínios realmente precisem de HTTP.
  4. Faça referência ao XML por meio de android:networkSecurityConfig.
  5. Teste novamente o endpoint bloqueado.

Resultado esperado: o destino especificado poderá usar HTTP, enquanto os demais destinos continuarão sujeitos às restrições do app para tráfego não criptografado. O sucesso depende de o domínio configurado corresponder ao host realmente usado em tempo de execução, inclusive qualquer destino de redirecionamento ou recurso de mídia.

Risco e reversão: esta é uma alteração de segurança de risco médio, sem expectativa de perda de dados. O tráfego não criptografado continua vulnerável mesmo quando o destino é confiável. Remova o domain-config ou migre o endpoint para HTTPS para reverter a exceção. Não amplie a configuração para domínios não relacionados nem ative includeSubdomains apenas para fazer a solicitação funcionar.

Comportamento por nível da API e alternativa com android:usesCleartextTraffic

No intervalo de destino relevante, o nível 28 e posteriores da API bloqueiam por padrão o tráfego não criptografado. A Configuração de segurança de rede permite controlar essa política a partir do nível 24 da API. Para o nível 23 e anteriores, as orientações fornecidas sobre versões do Android exigem android:usesCleartextTraffic além de uma estratégia de configuração de rede.

Uma Configuração de segurança de rede pode substituir android:usesCleartextTraffic no Android N e posteriores. Mais importante, a documentação oficial do atributo de aplicativo usesCleartextTraffic informa que o atributo é ignorado em apps destinados ao nível 38 ou superior da API. Portanto, ele não é um substituto compatível com versões futuras para a Configuração de segurança de rede.

Quando a alternativa ampla se aplica: use android:usesCleartextTraffic="true" somente para compatibilidade temporária ou quando todo o tráfego não criptografado precisar ser permitido em um intervalo de destino mais antigo e ainda não houver uma opção mais restrita por domínio.

Pré-requisitos:

  • Você entende que essa configuração reduz amplamente a segurança do transporte.
  • Você ainda não tem uma opção mais restrita e específica por domínio.
  1. Defina android:usesCleartextTraffic="true" no elemento do aplicativo.
  2. Verifique o manifesto mesclado no APK ou AAB compilado.
  3. Confirme se o app ainda bloqueia destinos não pretendidos caso também haja uma configuração de rede.
  4. Planeje a migração para a Configuração de segurança de rede ou HTTPS.

Resultado esperado: nos intervalos de destino em que o atributo é respeitado, o aplicativo poderá fazer solicitações não criptografadas, a menos que uma Configuração de segurança de rede efetiva imponha um comportamento diferente. Essa alternativa não funcionará em apps destinados ao nível 38 ou superior da API.

Risco e reversão: esta é uma alternativa de segurança de alto risco, pois pode permitir tráfego não criptografado em todo o aplicativo. Ela não apaga dados do aplicativo, mas pode expor os dados transmitidos à interceptação ou modificação. Para reverter, defina novamente o atributo como falso e remova as dependências de HTTP.

Verifique localhost, 10.0.2.2, IPs numéricos, redirecionamentos e URLs de mídia

Ambientes de desenvolvimento local e URLs de recursos geradas exigem verificação específica do app. Se o destino for localhost, um endereço de loopback, 10.0.2.2 ou um IP numérico, confirme o host realmente usado em tempo de execução e o ambiente de build pretendido antes de alterar a política. Relatos envolvendo esses destinos são sinais úteis para o diagnóstico, mas não determinam como a configuração de um app específico corresponderá ao host.

  • Confirme se o destino é usado apenas no desenvolvimento.
  • Verifique se a mesma política de tráfego não criptografado está sendo incluída por engano em um build de produção.
  • Inspecione redirecionamentos, playlists de mídia, recursos de CDN e URLs fornecidos pelo backend em busca de destinos HTTP.
  • Identifique se HttpURLConnection, OkHttp, WebView, MediaPlayer, DownloadManager, Media3, ExoPlayer ou um SDK de terceiros emitiu o erro antes de chegar a conclusões específicas sobre o componente.
  • Teste manualmente o host e a variante de build afetados, em vez de presumir que uma exceção de domínio corresponde a todos os destinos locais ou numéricos.

Não permita tráfego não criptografado em todo o aplicativo de produção apenas para atender a um servidor de desenvolvimento. Se HTTP for temporariamente inevitável, mantenha qualquer exceção confirmada limitada ao destino necessário e verifique se ela não é mais ampla do que o pretendido.

Confirme que o erro exato foi resolvido sem ampliar o acesso não criptografado

  1. Teste novamente a solicitação, a cadeia de redirecionamentos ou o fluxo de reprodução exato que produziu o erro originalmente.
  2. Teste a variante de build de destino afetada, em vez de presumir que uma variante representa todos os builds.
  3. Verifique novamente o manifesto mesclado e a Configuração de segurança de rede empacotada depois de alterar a política.
  4. Se uma exceção de domínio tiver sido usada, confirme que somente o destino necessário está permitido e que destinos HTTP não relacionados continuam bloqueados.
  5. Registre se o build é destinado ao nível 28 ou superior e ao nível 38 ou superior da API antes de interpretar o comportamento do manifesto.

A operação original deve ser concluída sem a assinatura de recusa de tráfego não criptografado, enquanto o aplicativo mantém a política mais restrita possível. Uma alteração isolada no arquivo-fonte não confirma a resolução. Se o erro persistir, verifique novamente o host em tempo de execução, a cadeia de redirecionamentos, os recursos da playlist, a configuração empacotada e a biblioteca de origem, em vez de ampliar a exceção.