Erro do Composer no Magento 2? Descubra o bloqueio em 8 testes antes de forçar a aplicação

Erro do Composer no Magento 2 pode interromper uma atualização, impedir a instalação de extensões ou deixar o código publicado diferente daquele que foi validado em homologação. Mensagens sobre dependências incompatíveis, memória, autenticação ou pacotes ausentes parecem semelhantes no terminal, mas exigem correções diferentes.

Antes de apagar o composer.lock, executar uma atualização geral ou repetir comandos como administrador, preserve a mensagem completa e descubra em qual etapa o processo falhou. Os oito testes abaixo ajudam a localizar o bloqueio sem transformar um problema de dependência em indisponibilidade da loja.

Erro do Composer no Magento 2: preserve o estado atual

Comece registrando o comando executado, o diretório da aplicação, o usuário do sistema, a versão do PHP e toda a saída apresentada no terminal. Uma captura contendo apenas a última linha pode esconder o pacote que iniciou o conflito.

Antes de qualquer alteração, preserve pelo menos estes arquivos:

• composer.json;
• composer.lock;
• auth.json, sem expor suas credenciais em chamados ou repositórios;
• arquivos de configuração alterados durante a manutenção;
• registro do commit ou pacote implantado.

Confira também o estado do Git com git status. Isso ajuda a distinguir uma mudança planejada de alterações geradas por uma tentativa anterior. Em produção, não prossiga com arquivos parcialmente atualizados: prepare a correção em uma cópia controlada ou em homologação.

1. Confirme qual PHP o Composer está usando

O PHP utilizado no terminal pode ser diferente daquele configurado no PHP-FPM do site. Assim, a loja pode abrir normalmente, mas o Composer recusar um pacote por requisito de versão ou extensão ausente.

php -v
which php
php --ini
php -m
composer --version

Observe principalmente a versão do PHP CLI e as extensões citadas na mensagem de erro. Não use opções para ignorar requisitos de plataforma como solução definitiva. Elas podem permitir a instalação de código que não funciona no servidor real.

Se o problema surgiu durante um upgrade, compare toda a infraestrutura exigida pela versão pretendida. O checklist de requisitos do Adobe Commerce antes do upgrade mostra por que PHP, banco, busca, cache e mensageria precisam ser avaliados em conjunto.

2. Diferencie composer install de composer update

Os dois comandos não são equivalentes. composer install instala as versões registradas no composer.lock. Ele é normalmente utilizado para reproduzir em outro ambiente um conjunto de dependências já resolvido e versionado.

composer update, por sua vez, recalcula versões conforme as restrições do composer.json e grava um novo lock. Executá-lo sem indicar pacotes pode alterar diversas dependências indiretas, ampliando o escopo da manutenção.

Se o objetivo é implantar um release previamente testado, confirme se o composer.lock correto foi enviado e prefira:

composer install --no-dev --prefer-dist --optimize-autoloader

Não inclua --no-dev em ambientes que dependam legitimamente das ferramentas de desenvolvimento. Já em um upgrade controlado, limite a atualização aos pacotes planejados e revise a diferença produzida no lock antes de aprová-la.

3. Peça ao Composer para explicar o conflito

Mensagens como “your requirements could not be resolved” indicam que duas ou mais restrições não podem ser atendidas simultaneamente. Em vez de testar versões aleatórias, identifique quem impede a instalação:

composer validate
composer why nome-do-pacote
composer why-not nome-do-pacote versao-desejada
composer prohibits nome-do-pacote versao-desejada

Substitua os exemplos pelo pacote e pela versão mencionados no erro. Verifique se o bloqueio vem do metapacote do Magento, de uma extensão, de uma biblioteca exigida por código personalizado ou de uma restrição adicionada diretamente ao projeto.

Uma extensão aparentemente pequena pode exigir uma versão incompatível de outra biblioteca. Atualizar apenas o pacote que aparece na última linha nem sempre resolve a cadeia.

4. Verifique as credenciais dos repositórios

Erros 401, 403, solicitações repetidas de usuário e mensagens de pacote inexistente podem decorrer de autenticação ou configuração do repositório. Inspecione as origens cadastradas sem publicar os segredos:

composer config --list
composer repo list

Confirme se as credenciais estão disponíveis para o usuário que executa o Composer. Um auth.json localizado no diretório pessoal de outro usuário não será necessariamente lido durante o deploy.

Evite colocar chaves diretamente no composer.json ou no histórico do shell. Se alguma credencial tiver sido exposta em log, repositório ou chamado público, trate-a como comprometida e providencie sua substituição.

5. Teste conectividade, DNS e certificados

Timeout, falha de resolução de nome e erro de certificado podem ser confundidos com indisponibilidade do pacote. Verifique se o servidor consegue resolver e acessar os domínios dos repositórios configurados, considerando proxy, firewall e inspeção TLS da infraestrutura.

composer diagnose
composer clear-cache

Limpar o cache pode ajudar quando um arquivo baixado está corrompido, mas não corrige DNS, proxy ou certificado inválido. Não desative a validação TLS para contornar a falha: isso reduz a segurança da cadeia de instalação. Corrija o certificado, a autoridade certificadora ou a configuração de rede responsável.

6. Analise memória e encerramentos do processo

Quando o processo termina com indicação de memória esgotada ou simplesmente é encerrado, descubra se o limite pertence ao PHP, ao contêiner ou ao sistema operacional. Compare:

php -r "echo ini_get('memory_limit'), PHP_EOL;"
free -h
df -h

Também confira os logs do sistema ou da plataforma de hospedagem para identificar uma finalização pelo gerenciador de memória. Aumentar o limite indiscriminadamente pode apenas adiar o problema, sobretudo quando há pouca memória disponível ou espaço insuficiente para arquivos temporários.

Execute operações pesadas em homologação ou no processo de build sempre que a arquitetura permitir. Isso evita disputar CPU e memória com checkout, Admin, consumidores e cron.

7. Confirme permissões e propriedade dos arquivos

Mensagens como “permission denied” podem aparecer ao gravar em vendor, generated ou no próprio composer.lock. Verifique quem é o proprietário dos arquivos e qual usuário realiza o deploy:

id
ls -la composer.json composer.lock vendor 2>/dev/null

Não transforme diretórios em graváveis por todos e não execute o Composer como root apenas para silenciar o erro. Corrija a propriedade e as permissões conforme o modelo de implantação do ambiente.

Permissões incoerentes aparecem com frequência quando comandos anteriores foram executados por usuários diferentes. Se a aplicação ficou indisponível depois de uma publicação, consulte também o roteiro para recuperar o Magento 2 após um deploy sem apagar as evidências.

8. Revise plugins, scripts e o resultado antes de publicar

Nem toda falha acontece durante a resolução ou o download. O Composer pode concluir essas etapas e parar em um plugin ou script definido pelo projeto. Execute o comando com mais detalhes em homologação:

composer install -vvv

A saída detalhada ajuda a localizar o último pacote, plugin ou script executado. Desabilitar plugins ou scripts pode ser útil como teste diagnóstico em um ambiente isolado, mas não significa que o resultado esteja pronto para produção. Esses componentes podem executar tarefas necessárias ao pacote.

Depois de corrigir o bloqueio, revise as mudanças em composer.json e composer.lock, faça o build completo e valide ao menos:

• página inicial, categorias, produtos e busca;
• login, carrinho e checkout;
• métodos de pagamento e cálculo de frete;
• Admin, cron, filas e indexadores;
• integrações com ERP, marketplaces e serviços externos;
• logs da aplicação e resposta dos serviços de infraestrutura.

Se a intervenção afetar catálogo ou índices, não inicie uma reindexação geral sem diagnóstico. O guia sobre indexadores Magento 2 travados ajuda a identificar filas e índices afetados antes de aumentar a carga do ambiente.

O que evitar durante a correção

• apagar o composer.lock para “deixar o Composer escolher” em produção;
• executar composer update geral sem revisar os pacotes alterados;
• ignorar requisitos de PHP ou extensões para concluir a instalação;
• usar root ou permissões abertas como correção permanente;
• desativar TLS para contornar problemas de certificado;
• publicar uma pasta vendor parcial após a interrupção do comando;
• testar a correção diretamente durante o pico de vendas.

Perguntas frequentes

Posso apagar o composer.lock quando a atualização falha?

Não como primeira tentativa, especialmente em produção. O arquivo registra as versões exatas das dependências e permite reproduzir o build. Apagá-lo amplia o número de pacotes recalculados e pode introduzir mudanças não planejadas.

Qual é a diferença entre composer install e composer update?

O composer install utiliza as versões registradas no lock. O composer update recalcula dependências conforme o composer.json e modifica o lock. Em deploys, normalmente é necessário reproduzir o conjunto já testado, não recalculá-lo no servidor.

É seguro usar ignore-platform-reqs no Magento 2?

Não como correção definitiva. A opção ignora requisitos de plataforma durante a resolução, mas o código ainda pode depender da versão do PHP ou de extensões ausentes. Use o diagnóstico para ajustar o ambiente ou selecionar pacotes compatíveis.

Por que o Composer funciona localmente e falha no servidor?

Os ambientes podem usar versões diferentes de PHP, extensões, credenciais, memória, certificados, DNS ou arquivos de lock. Compare essas condições e confirme que o mesmo usuário e o mesmo conjunto de arquivos são usados no processo de build.

Conclusão

Um erro do Composer no Magento 2 deve ser tratado como um problema reproduzível de plataforma, dependência ou implantação. Preservar o lock, interpretar a cadeia de conflito e validar o resultado em homologação é mais seguro do que forçar a instalação até o comando terminar.

Se a sua equipe precisa localizar o pacote incompatível, preparar um upgrade ou recuperar uma implantação interrompida, o suporte especializado em Magento pode ajudar a conduzir o diagnóstico e planejar a correção com menor impacto operacional.