Quando uma aplicação rodando no Azure App Service começa a retornar um comportamento de HTTP 404 – Not Found, a equipe de engenharia pode ser levada a acreditar que se trata de uma falha de deployment ou código, especialmente se o portal indica o service como Running. No entanto, esse é um cenário clássico de visibilidade operacional limitada.
O que o HTTP 404 realmente significa no Azure App Service?
De uma perspectiva de observability, um status 404 confirma que o tráfego atingiu o front-end do seu App Service com sucesso. Isso descarta problemas na camada de rede (DNS, VNet, ou limites de firewall). O problema não é de conectividade; a falha ocorre dentro do pipeline de roteamento ou na execução da aplicação. Em suma: a requisição chegou, mas o handler ou a rota esperada não foi encontrada.
Causas Raízes e Pontos de Atenção
1. Incoerência de Rotas
É a causa mais comum. Muitas vezes, o contexto da aplicação espera prefixos de API (/api, /v1) que não estão sendo enviados na requisição. Além disso, em ambientes Linux App Service, o sistema de arquivos é case-sensitive, o que pode causar 404s que não ocorrem em ambientes Windows.
2. Falhas no Startup da Aplicação
O App Service pode reportar o status como Running mesmo que a inicialização tenha sido parcial. Se o Program.cs ou Startup.cs falhar ao configurar o middleware de rotas devido a uma connection string inválida ou falha no dependency injection, o host passará a responder, mas sem registrar os endpoints. Verifique os logs no Kudu (via LogFiles) para confirmar se houve uma falha silenciosa no JIT ou na injeção de dependências.
3. Gestão de Conteúdo Estático
Se a sua aplicação serve arquivos estáticos (JS, CSS, Imagens), certifique-se de que os artefatos foram descompactados no diretório esperado (/home/site/wwwroot). Se você estiver usando o cenário de Run from Package, garanta que o arquivo .zip esteja íntegro e que as permissões de leitura estejam corretas.
4. Diferenças de Comportamento entre Windows e Linux
Ao migrar workloads de Windows para o App Service no Linux, o roteamento via Nginx assume diferentes tratamentos. Se um endpoint funciona perfeitamente no ambiente local (geralmente Windows ou Docker desktop) e falha no Linux, foque na padronização de caminhos (casing) e nos comandos de startup definidos no portal.
5. Health Checks e Probes
Se o 404 aparece periodicamente, é provável que o seu Health Check esteja apontando para uma rota que não existe ou está protegida por políticas de autenticação que a sonda não consegue validar.
Checklist de Resolução para Times de Engenharia
- Valide a URL exata: Compare o que o Front-door ou o load balancer está recebendo com o que está mapeado na aplicação.
- Debug via Kudu: Não confie apenas no portal. Acesse a console do Kudu e liste o diretório
wwwrootpara confirmar a presença física dos arquivos. - Logs de Deployment: Mesmo se o
deployment statusfor Success no CI/CD, revise os logs no portal para identificar se algum passo foi ignorado ou se oWEBSITE_RUN_FROM_PACKAGEestá aplicando uma versão antiga. - Application Gateway: Se você utiliza um serviço de gateway na entrada, valide as rewrite rules. Frequentemente, o 404 é gerado pelo redirecionamento incorreto de pacotes para caminhos internos inexistentes.
Ao abordar erros 404 no Azure seguindo uma trilha de plataforma -> configuração -> aplicação, você isola o problema com muito mais velocidade, reduzindo o MTTR (Mean Time To Repair) e estabilizando sua infraestrutura em produção.
Artigo originalmente publicado em Azure Updates - Latest from Azure Charts.
