Erros de deploy no Azure App Service ficaram mais fáceis de interpretar com --enriched-errors

Falhas de deployment sempre foram um dos momentos mais frustrantes para times de engenharia — especialmente quando a mensagem de erro do Azure CLI é genérica demais para indicar a causa raiz. A Microsoft acaba de lançar um recurso que muda esse cenário para quem usa Azure App Service (Linux).

TL;DR: A partir de 2026, o Azure CLI para App Service Linux inclui o parâmetro --enriched-errors, que substitui mensagens genéricas de falha por diagnósticos completos: código de erro, stack do runtime, raw error e sugestões de correção. Para empresas brasileiras que dependem de CI/CD no Azure, isso reduz drasticamente o tempo de debugging em deployments – especialmente em casos de incompatibilidade de artefato, runtime ou configuração como WEBSITE_RUN_FROM_PACKAGE.

Como usar o parâmetro --enriched-errors?

Adicione --enriched-errors true ao seu comando de deployment:

Copiaraz webapp deploy \
  --resource-group <resource-group-name> \
  --name <app-name> \
  --src-path <path-to-package> \
  --enriched-errors true

Simples: uma flag extra e você começa a receber diagnósticos muito mais acionáveis diretamente no terminal.

O que você obtém com erros enriquecidos?

Com a flag ativada, em caso de falha o output do CLI passa a incluir detalhes como os do exemplo abaixo:

CopiarError Code  : ArtifactStackMismatch
Stage       : Deployment
Runtime     : DOTNETCORE|9.0
Deploy Type : WarDeploy
Kudu Status : 400

Raw Error:
Artifact type = 'War' cannot be deployed to stack = 'DOTNETCORE'.

Suggested Fixes:
- Ensure the artifact type matches the app's runtime stack
- Check the current linuxFxVersion
- Update the runtime stack if needed

Isso cobre cenários como mismatch entre artefato e runtime, caminho de deploy inválido, parâmetros obrigatórios ausentes e conflitos de configuração como WEBSITE_RUN_FROM_PACKAGE. As capturas de tela abaixo mostram mais exemplos:

Como usar o GitHub Copilot com os erros enriquecidos?

O output também inclui um prompt pronto para ser colado no GitHub Copilot junto com os detalhes completos do erro:

Why did my Linux App Service deployment fail and how do I fix it?

Isso permite que o Copilot ofereça uma análise mais específica baseada na sua configuração real e no erro exato que ocorreu – útil para times que já adotam IA generativa no fluxo de troubleshooting.

Resumo: quando adotar esse recurso

O novo switch --enriched-errors transforma o Azure CLI em uma ferramenta de diagnóstico muito mais eficiente para deployments no App Service Linux. Se sua equipe sofre com horas perdidas tentando entender por que um deploy falhou, ativar essa flag é uma intervenção de baixo custo e alto retorno em produtividade – especialmente válida para empresas brasileiras que mantêm pipelines críticos no Azure.

Perguntas Frequentes

• Como habilitar os erros enriquecidos no Azure CLI?
  Basta adicionar o parâmetro --enriched-errors true ao comando az webapp deploy. Por padrão, ele vem desabilitado, então é necessário ativá-lo explicitamente para obter os diagnósticos detalhados.

• Quais tipos de erro são identificados pelo --enriched-errors?
  O recurso detecta problemas como incompatibilidade entre o tipo de artefato e o runtime do app (ex: tentar fazer deploy de um arquivo WAR em um stack DOTNETCORE), caminho de deploy inválido, parâmetros obrigatórios faltando e conflitos de configuração como WEBSITE_RUN_FROM_PACKAGE.

• Esse recurso funciona apenas para Linux?
  Sim, o parâmetro --enriched-errors foi adicionado exclusivamente para o comando az webapp deploy em App Service para Linux. Não há menção de suporte para Windows no artigo original.

• Posso usar o output com GitHub Copilot? Como?
  Sim. O output enriquecido inclui um prompt pronto para ser colado no GitHub Copilot junto com os detalhes do erro, como "Why did my Linux App Service deployment fail and how do I fix it?". O Copilot pode então fornecer orientação adicional baseada na sua configuração.

• O que significa o código de erro ArtifactStackMismatch?
  Esse código indica que o tipo de artefato que você está tentando implantar não é compatível com o runtime configurado no App Service. Por exemplo, tentar fazer deploy de um arquivo WAR em um app configurado com DOTNETCORE. A solução sugerida é ajustar o runtime ou o tipo de artefato.

---

Artigo originalmente publicado por TulikaC em Azure Updates - Latest from Azure Charts.