INSTALL_FAILED_UPDATE_INCOMPATIBLE, acompanhado da mensagem de incompatibilidade de assinaturas Package <package_name> signatures do not match the previously installed version; ignoring!, indica que o Android rejeitou o APK recebido por considerá-lo uma atualização não autorizada de um pacote existente. Isso ocorre durante a implantação de APKs pelo Android Studio, ADB, dispositivos físicos, emuladores e outros instaladores de pacotes. A ação inicial mais segura é manter a instalação existente intacta enquanto você verifica o dispositivo de destino, o pacote, o usuário do Android e o certificado de assinatura do APK recebido.

O que significa INSTALL_FAILED_UPDATE_INCOMPATIBLE

O Android identifica uma atualização usando tanto o ID do aplicativo, também chamado de nome do pacote, quanto a identidade de assinatura autorizada. Um APK só pode atualizar o aplicativo existente quando o ID do aplicativo é igual e o certificado de assinatura corresponde ao do aplicativo instalado, ou quando uma prova de rotação válida estabelece um histórico de assinatura autorizado. Esse requisito está documentado em Como as atualizações de apps funcionam.

O texto exato apresentado pelo instalador pode variar conforme o instalador e a versão do Android. A documentação oficial do Android estabelece a regra do certificado, mas não publica uma única mensagem universal para todas as versões.

Entre os contextos comuns confirmados estão um APK de depuração substituindo uma versão de lançamento, um APK local substituindo uma versão distribuída pelo Google Play, uma instalação anterior no emulador ou dispositivo selecionado e um estado de pacote pertencente a outro usuário do Android ou perfil de trabalho. Um código de versão válido continua sendo necessário para uma atualização normal, mas não pode autorizar um certificado de assinatura diferente.

Verifique o dispositivo de destino, o pacote e o usuário do Android

Faça isso antes de alterar as configurações de assinatura ou remover qualquer item. Substitua SERIAL, USER_ID e PACKAGE_NAME somente por valores que você tenha verificado.

  1. Execute adb devices -l.
  2. Identifique o dispositivo físico ou emulador pretendido e anote o número de série.
  3. Confirme o ID exato do aplicativo ou o nome do pacote.
  4. Consulte esse pacote para o usuário relevante com adb -s SERIAL shell pm list packages --user USER_ID PACKAGE_NAME.

Comandos associados a um número de série são importantes quando há vários dispositivos ou emuladores conectados. A documentação oficial do Android Debug Bridge (ADB) descreve a seleção do destino e as operações do gerenciador de pacotes usadas aqui.

Resultado esperado: a consulta identifica o estado existente do pacote para esse usuário ou não retorna nenhum pacote correspondente. Um resultado vazio para o usuário principal não comprova que todos os usuários secundários ou perfis gerenciados estejam livres desse pacote. Verifique esses contextos separadamente antes de desinstalar qualquer item.

Risco e reversão: esses comandos inspecionam os destinos e o estado do pacote sem remover intencionalmente o aplicativo. Se houver dúvida sobre o número de série, o nome do pacote ou o usuário, pare em vez de prosseguir com um comando destrutivo.

Inspecione o certificado de assinatura do APK recebido

Inspecione o APK que você está realmente tentando implantar:

  1. Execute apksigner verify --print-certs app.apk.
  2. Compare o certificado exibido com a configuração de assinatura autorizada conhecida do aplicativo, quando você tiver acesso a ela.
  3. Se os certificados forem diferentes e nenhuma linhagem de assinatura válida se aplicar, interrompa a tentativa de atualização.

A identidade relevante pode ser um certificado de depuração, um certificado de lançamento gerenciado localmente ou o certificado de assinatura usado em uma versão distribuída pelo Google Play. Um certificado de upload não é necessariamente o certificado usado para assinar APKs entregues pelo Google Play. A documentação Assinar seu aplicativo explica a comparação de certificados e a diferença entre a chave de assinatura do aplicativo e a chave de upload.

O Android 9 e versões posteriores oferecem suporte à prova de rotação do APK Signature Scheme v3. Uma linhagem de rotação válida pode autorizar um certificado mais recente, mas apenas gerar ou selecionar uma chave diferente não produz essa autorização. O acesso a um APK instalado ou ao certificado dele também pode ser restrito. Por isso, talvez seja necessário confirmar a identidade instalada usando registros de lançamento conhecidos, em vez de deduzi-la.

Resultado esperado: você determina se o APK recebido usa a identidade de assinatura autorizada do aplicativo ou uma linhagem válida. A inspeção do certificado não modifica o aplicativo instalado.

Preserve os dados do aplicativo recriando o APK com a identidade de assinatura autorizada

Quando se aplica: use este caminho preferencial quando a instalação existente e os dados locais precisarem ser preservados, o ID do aplicativo não tiver sido alterado e você controlar a chave correta de assinatura do aplicativo ou um processo de rotação válido. O versionCode do APK recebido não pode ser menor que o da versão instalada.

Pré-requisitos:

  • O número de série, o usuário e o nome do pacote pretendidos foram verificados.
  • Você tem acesso à configuração de assinatura estabelecida do aplicativo ou a uma prova de rotação válida.
  • Você não removeu a instalação existente.
  1. Execute adb devices -l e selecione o número de série pretendido.
  2. Execute adb -s SERIAL shell pm list packages --user USER_ID PACKAGE_NAME.
  3. Inspecione o APK recebido com apksigner verify --print-certs app.apk.
  4. Gere o APK usando a configuração de assinatura estabelecida do aplicativo.
  5. Instale-o no destino selecionado com adb -s SERIAL install -r app.apk.
  6. Se os certificados forem diferentes, pare. Não espere que a alteração do código de versão, a limpeza do cache ou uma compilação limpa autorize a atualização.

Resultado esperado: o Android aceita o APK como uma atualização autorizada se o ID do aplicativo, os requisitos de versão e a identidade de assinatura ou linhagem válida atenderem às verificações de atualização. Isso não pode ser garantido sem verificar o estado do pacote no dispositivo específico.

Risco e reversão: o risco é baixo porque o pacote existente é mantido. Se a instalação continuar sendo rejeitada, preserve a instalação atual e recrie o APK com a configuração de assinatura autorizada, em vez de substituí-la por uma nova chave privada.

Trate um aplicativo instalado pelo Google Play

Quando se aplica: use este caminho quando a cópia instalada tiver vindo do Google Play e o APK local estiver assinado com uma chave de upload ou outra chave local.

Pré-requisitos: a Assinatura de apps do Google Play está ativada, e você tem acesso a uma faixa de teste aprovada, ao Compartilhamento interno de apps ou a artefatos de lançamento gerados pelo Google Play.

  1. Confirme se a Assinatura de apps do Google Play gerencia a chave de assinatura do aplicativo distribuído.
  2. Não compare o aplicativo instalado apenas com o certificado da chave de upload. A chave de upload e a chave de assinatura do aplicativo distribuído podem ser diferentes.
  3. Use o Compartilhamento interno de apps para testar o que o Google Play entrega ou faça o download dos artefatos de APK gerados pelo Google Play.
  4. Para APKs divididos baixados localmente, use adb install-multiple conforme documentado.
  5. Use um APK assinado localmente somente se ele tiver a mesma identidade autorizada de assinatura do aplicativo.

Em upgrades da chave de assinatura do Google Play, o Android 13 e versões posteriores podem receber APKs assinados com a chave atualizada, enquanto versões anteriores do Android recebem atualizações assinadas com a chave antiga.

Resultado esperado: o artefato de teste é distribuído com uma identidade de assinatura compatível com a versão instalada pelo Google Play. A correspondência apenas com a chave de upload não comprova a compatibilidade.

Risco e reversão: o risco é baixo quando o aplicativo instalado pelo Google Play permanece no dispositivo. Preserve-o e retorne ao caminho apropriado de teste do Google Play se o artefato local não puder ser autorizado.

Verifique usuários secundários, perfis de trabalho e dispositivos gerenciados

Quando se aplica: use este caminho de diagnóstico quando o aplicativo parecer ausente no perfil principal ou o dispositivo tiver usuários secundários, um perfil de trabalho, um perfil gerenciado ou um isolamento de pacotes semelhante à Pasta Segura.

Pré-requisitos: acesso à depuração por USB ou sem fio e permissão para inspecionar o dispositivo. As políticas empresariais podem limitar a visibilidade e as operações de pacote.

  1. Selecione o destino pretendido usando adb -s SERIAL.
  2. Liste os usuários com adb -s SERIAL shell pm list users.
  3. Para cada ID relevante, execute adb -s SERIAL shell pm list packages --user USER_ID PACKAGE_NAME.
  4. Use explicitamente o ID de usuário verificado nos comandos posteriores do gerenciador de pacotes.
  5. Se um perfil empresarial controlar o pacote, use o procedimento administrativo aprovado pela organização.
  6. Não tente contornar as restrições da política do dispositivo.

Resultado esperado: você identifica se o estado conflitante do pacote pertence a outro usuário ou perfil. O isolamento de perfis pode tornar um aplicativo invisível no perfil principal, mas essa é uma possibilidade que precisa ser verificada, não uma causa presumida.

Risco e reversão: a inspeção não é destrutiva, mas a propriedade e a visibilidade dos perfis variam. Pare se a política ou a propriedade não estiver clara. Não é necessária nenhuma reversão para os comandos de inspeção apresentados.

Remova uma instalação de teste conflitante somente se os dados puderem ser descartados

Aviso de perda de dados: a desinstalação pode excluir os dados locais do aplicativo. A reinstalação recupera o binário do aplicativo, mas não os dados excluídos. Continue apenas com uma instalação de teste descartável ou depois de aceitar explicitamente a perda e verificar qualquer backup independente necessário.

Quando se aplica: use esta alternativa destrutiva somente quando não for necessário preservar a instalação existente ou quando a identidade de assinatura autorizada correta não estiver disponível e uma instalação nova for aceitável.

Pré-requisitos:

  • O número de série, o nome do pacote e o escopo do usuário foram verificados.
  • Os dados de teste necessários foram exportados para um local independente ou são comprovadamente descartáveis.
  • O pacote não está sujeito a uma remoção não aprovada de um perfil gerenciado.
  1. Confirme o destino com adb devices -l.
  2. Confirme o pacote e o usuário com adb -s SERIAL shell pm list packages --user USER_ID PACKAGE_NAME.
  3. Para um único usuário, execute adb -s SERIAL shell pm uninstall --user USER_ID PACKAGE_NAME.
  4. Instale o APK substituto depois da remoção.
  5. Recrie ou restaure somente os dados disponíveis em um backup independente e utilizável.

Aviso: sem --user, pm uninstall remove o pacote de todos os usuários do dispositivo por padrão. Não omita o escopo do usuário sem uma verificação cuidadosa.

Resultado esperado: o APK substituto é tratado como uma instalação nova para o usuário selecionado, e não como uma atualização da instalação conflitante.

Risco e reversão: o risco é alto. A reinstalação pode recuperar o binário, mas não pode restaurar os dados locais excluídos, a menos que exista um backup separado e utilizável.

O que não corrige esse erro e como descartar outras falhas de instalação

  • Incrementar o versionCode: isso é necessário quando as regras normais de atualização o exigem, mas não pode autorizar um APK assinado com um certificado diferente.
  • Limpar os caches do Gradle: isso não altera a identidade de assinatura do APK.
  • Limpar e recompilar sem corrigir a assinatura: a recompilação só ajuda se restaurar a configuração de assinatura autorizada.
  • Limpar o armazenamento do aplicativo ou excluir arquivos visíveis: isso não altera a identidade de assinatura autorizada do pacote.
  • Comparar somente a chave de upload do Google Play: o APK distribuído pelo Google Play pode usar outro certificado de assinatura do aplicativo.
Erro Diferença específica
INSTALL_FAILED_UPDATE_INCOMPATIBLE O pacote existente e o APK recebido não têm uma relação de assinatura autorizada.
INSTALL_FAILED_VERSION_DOWNGRADE A versão recebida é anterior. Esse não é o diagnóstico de conflito de certificados abordado aqui.
INSTALL_FAILED_INVALID_APK O instalador considera o APK inválido, em vez de considerá-lo uma atualização assinada não autorizada.
INSTALL_FAILED_INSUFFICIENT_STORAGE Não há espaço de armazenamento disponível suficiente para a instalação; o problema não é uma identidade de assinatura compatível.

A resolução é confirmada quando o destino pretendido aceita o APK como uma atualização autorizada ou quando uma instalação descartável, removida de forma deliberada, aceita o APK como uma instalação nova. Se a instalação for concluída, mas o aplicativo depois apresentar uma exceção de execução não relacionada ao compartilhamento de arquivos, consulte como corrigir android.os.FileUriExposedException no Android.