Corrigir ForegroundServiceDidNotStartInTimeException no Android

ForegroundServiceDidNotStartInTimeException significa que o Android iniciou um serviço em primeiro plano por meio de Context.startForegroundService() ou ContextCompat.startForegroundService(), mas o novo serviço não fez a promoção com ServiceCompat.startForeground() ou Service.startForeground() dentro de alguns segundos. Isso afeta a API 26 e versões posteriores. O Android 12 e versões posteriores identificam a exceção diretamente, enquanto o Android 8.0 até o Android 11 pode informar RemoteServiceException com a mesma mensagem. A primeira ação mais segura é confirmar a assinatura exata no Logcat e determinar se o caminho que causa a falha é um serviço nativo ou um worker em primeiro plano do WorkManager.

Confirme a exceção exata e a versão do Android

Procure a mensagem Context.startForegroundService() did not then call Service.startForeground(). De acordo com a documentação de solução de problemas de serviços em primeiro plano do Android, o Android gera essa família de exceções quando um serviço iniciado com startForegroundService() não chama startForeground() dentro do intervalo de inicialização permitido.

Plataforma ou caminho	Assinatura esperada	Próxima etapa
Android 12 e versões posteriores	`ForegroundServiceDidNotStartInTimeException` com a mensagem correspondente	Determine se o app usa um serviço nativo ou um worker em primeiro plano do WorkManager
Android 8.0 a 11	`RemoteServiceException` com a mesma mensagem de `startForegroundService()`/`startForeground()`	Use o mesmo diagnóstico de tempo da promoção do serviço nativo, a menos que o marcador do WorkManager também esteja presente
Worker em primeiro plano do WorkManager	A família da exceção e, para a condição de corrida documentada, `Re-initializing SystemForegroundService after a request to shut-down`	Use o procedimento específico do WorkManager somente quando esse marcador secundário aparecer

A referência de Context.startForegroundService fornece o contexto da API que aciona o serviço. Não classifique toda RemoteServiceException como essa falha; a mensagem correspondente precisa estar presente.

Descarte falhas relacionadas de serviços em primeiro plano

ForegroundServiceStartNotAllowedException diz respeito à permissão do Android para iniciar o serviço em segundo plano. É uma falha distinta do Android 12 e versões posteriores, abordada nas restrições do Android para iniciar serviços em primeiro plano a partir do segundo plano.
Falhas por limite de duração de serviços em primeiro plano e ANRs de serviços de curta duração ocorrem após limites de execução diferentes. Elas não são variantes dessa falha de promoção durante a inicialização.
Uma SecurityException relacionada ao tipo ou à permissão do serviço em primeiro plano também pertence a outra família de falhas, mesmo que ocorra perto da chamada de promoção.

Se a mensagem exata estiver ausente, não aplique este guia como se as falhas fossem equivalentes.

Corrija um serviço nativo que não faz a promoção em tempo hábil

Quando se aplica: use este caminho confirmado quando o código do app inicia um serviço nativo com startForegroundService() ou ContextCompat.startForegroundService(), e o Logcat contém a mensagem exata de falha na promoção durante a inicialização. Não use este procedimento como substituto para diagnosticar uma restrição de inicialização em segundo plano ou uma condição de corrida do WorkManager.

Pré-requisitos:

Um canal de notificação válido no Android 8.0 e versões posteriores.
A notificação do serviço em primeiro plano criada antes da promoção.
ServiceCompat disponível no código do app ao usar ServiceCompat.startForeground().

Os requisitos de notificação, manifesto e tipo de serviço em primeiro plano podem variar conforme o tipo de serviço e a versão do Android. Verifique os requisitos específicos do app antes de presumir que a chamada de promoção é válida. Este guia não cria declarações que não tenham sido confirmadas para o app.

Crie o canal de notificação antes da promoção. O canal já precisa estar disponível quando a notificação do serviço em primeiro plano for usada.
Crie imediatamente a notificação do serviço em primeiro plano. Não deixe a criação da notificação para depois de acessos à rede, operações de disco ou outras inicializações demoradas.
Chame ServiceCompat.startForeground() dentro de alguns segundos após o início do serviço. Service.startForeground() cumpre a mesma finalidade de promoção quando usado diretamente. Não presuma nem dependa de um prazo exato mais longo.
Transfira o trabalho principal para depois da promoção. Acesso à rede, operações de disco e outras inicializações demoradas não podem bloquear a promoção obrigatória.
Revise todos os caminhos condicionais e de ciclo de vida. Confirme que toda nova instância do serviço chega à promoção para primeiro plano, incluindo ramificações que retornam antecipadamente ou tratam ações de inicialização diferentes.

Resultado esperado: cada nova instância do serviço entra em primeiro plano antes do início do trabalho principal, e a exceção exata não deve voltar a ocorrer quando o cenário original de inicialização for testado novamente. Esse resultado precisa ser verificado, não presumido.

Risco: baixo. Antecipar a promoção pode alterar o momento em que a notificação visível ao usuário aparece e revelar problemas específicos do app relacionados à notificação ou ao manifesto que antes ocorriam mais tarde.

Reversão: se a alteração no ciclo de vida causar uma regressão, restaure o fluxo anterior do serviço durante a investigação. Mantenha a falha original observável em testes controlados, em vez de ocultá-la.

Não adicione uma espera arbitrária, não transfira a promoção para um callback posterior e não substitua startForegroundService() por startService() como solução genérica. Essas ações não são correções compatíveis com essa exceção e podem agravar ou ocultar a falha de tempo.

Se a sequência de promoção pretendida não for alcançada de forma consistente, inspecione manualmente as ramificações do ciclo de vida do app. Relatos da comunidade mencionam interações com stopSelf(), stopService() e publicação atrasada de notificações, mas as evidências oficiais fornecidas não confirmam uma correção universal para esses padrões. Trate-os como diagnósticos específicos do app, não como correções confirmadas adicionais.

Use a correção do WorkManager somente quando o marcador de desligamento aparecer

Quando se aplica: use este caminho somente quando o fluxo que causa a falha for um worker em primeiro plano do WorkManager que usa setForeground() ou setForegroundAsync(), e o Logcat incluir o marcador secundário exato Re-initializing SystemForegroundService after a request to shut-down. Sem esse marcador, não presuma que a condição de corrida documentada do WorkManager causou a falha.

Pré-requisitos:

O caminho afetado precisa usar um worker em primeiro plano do WorkManager.
O marcador exato de desligamento e reinicialização precisa estar presente no Logcat.

Confirme o marcador no Logcat. Preserve a exceção ao redor do marcador e o contexto do worker para não confundir a condição de corrida com uma falha de tempo de um serviço nativo.
Atualize para a versão mantida mais recente do WorkManager disponível para o projeto. O WorkManager 2.10.5 introduziu a correção documentada para essa falha causada pela sobreposição com o desligamento. Essa versão não deve ser descrita como a versão atual sem uma verificação no momento da publicação.
Teste novamente o cenário com workers em primeiro plano sobrepostos. Use o mesmo tempo de execução e o mesmo acionador do worker que causaram a falha anteriormente.
Informe um problema restante no rastreador de problemas do WorkManager. Inclua a exceção exata, o marcador de desligamento e os detalhes de reprodução caso o caminho de atualização documentado não resolva o cenário testado.

Resultado esperado: o WorkManager não deve mais reproduzir a falha documentada de desligamento e reinicialização do SystemForegroundService durante o mesmo teste com workers sobrepostos. Isso não comprova que falhas não relacionadas dos workers tenham sido corrigidas.

Risco: baixo, mas uma atualização de dependência pode introduzir outras alterações de comportamento. Faça testes de regressão nos comportamentos relevantes dos workers em primeiro plano e do trabalho em segundo plano.

Reversão: volte a fixar a versão anterior somente se a atualização do WorkManager introduzir uma regressão não relacionada. Caso contrário, mantenha a versão com suporte que contém a correção documentada.

Verifique se todas as instâncias do serviço são promovidas em tempo hábil

A verificação precisa reproduzir o acionador original sem ocultar a exceção nem adicionar alterações de tempo apenas para fazer o teste passar.

Repita o cenário original. Inicie o mesmo serviço nativo ou reproduza a mesma sequência de workers em primeiro plano sobrepostos que causou a falha anteriormente.
Mantenha a falha observável. Não capture, oculte nem atrase a exceção como prova de correção.
Em um serviço nativo, inspecione todos os caminhos. Confirme que cada nova instância cria a notificação válida e chega à promoção para primeiro plano antes de acessar a rede, o disco ou executar outro trabalho principal.
No WorkManager, repita a sobreposição após a atualização. Confirme que o teste segue o mesmo caminho do worker em primeiro plano e que a versão mantida do WorkManager está realmente em uso.
Analise o Logcat. Verifique se Context.startForegroundService() did not then call Service.startForeground() voltou a ocorrer. No caminho do WorkManager, verifique também Re-initializing SystemForegroundService after a request to shut-down.
Faça testes de regressão do comportamento. Verifique o momento em que a notificação aparece para o usuário e o comportamento relevante de execução em segundo plano nas versões do Android compatíveis com o app.

A correção só é sustentada depois que o acionador original deixa de reproduzir a exceção exata em todos os caminhos relevantes do serviço. Uma única inicialização não relacionada do app não é uma verificação suficiente, e nenhum procedimento deve ser tratado como garantido.

Perguntas frequentes

O que causa ForegroundServiceDidNotStartInTimeException?

A exceção ocorre quando um serviço iniciado com startForegroundService() não chama startForeground() dentro do intervalo de inicialização permitido. No Android 8.0 ao 11, a mesma falha pode aparecer como RemoteServiceException com a mensagem correspondente.

ForegroundServiceStartNotAllowedException é a mesma falha?

Não. ForegroundServiceStartNotAllowedException indica uma restrição para iniciar um serviço em primeiro plano a partir do segundo plano. Ela é diferente da falha causada pela ausência de promoção do serviço em tempo hábil.

Quando a atualização do WorkManager se aplica?

Somente quando o caminho afetado usa um worker em primeiro plano e o Logcat contém o marcador exato Re-initializing SystemForegroundService after a request to shut-down. O WorkManager 2.10.5 introduziu a correção documentada para essa condição de corrida.