Preference do di.xml não aplica no Magento 2: o que checar antes

A preference está escrita, o módulo aparece como habilitado e o Magento 2 continua instanciando a classe original como se o seu arquivo não existisse. Antes de xingar o compilador, olhe em qual pasta o di.xml foi salvo: área errada é a causa da maioria dos chamados desse tipo que caem na minha mão.

A área do arquivo manda mais que o conteúdo

O etc/di.xml vale para tudo. O etc/frontend/di.xml só carrega em requisição de loja, o etc/adminhtml/di.xml só no painel e o etc/webapi_rest/di.xml só na API REST. Se a classe que você quer trocar roda dentro de um cron, de um consumer de fila ou de um comando de console, a preference precisa estar no di.xml global:

<?xml version="1.0"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="urn:magento:framework:ObjectManager/etc/config.xsd">
    <preference for="MagentoCatalogApiProductRepositoryInterface"
                type="RogerCatalogoModelProductRepository"/>
</config>

Depois é limpeza de DI, não de cache de página

O mapa de preferences sai do merge de todos os di.xml e fica guardado no cache de tipo config, enquanto as fábricas, os proxies e os interceptors ficam em generated/. Limpar o full page cache não toca em nenhum dos dois:

bin/magento module:status Roger_Catalogo
bin/magento dev:di:info "MagentoCatalogApiProductRepositoryInterface"
rm -rf generated/code generated/metadata
bin/magento cache:clean config
bin/magento setup:di:compile

O dev:di:info mostra qual preference o Magento carregou de fato para aquela interface; se vier a classe original, o problema é o arquivo, não o cache. Em loja no ar, apagar o generated/ derruba as requisições até o compile terminar, então suba o bin/magento maintenance:enable antes ou compile em outra pasta e troque o symlink.

Em modo developer o Magento regenera o generated/code sozinho na primeira chamada, e é exatamente por isso que a preference funciona na sua máquina e morre no servidor em produção, onde o compile é obrigatório.

Continuou ignorando? Rode grep -rl ProductRepositoryInterface app/code vendor --include=di.xml e veja se outro módulo declara preference para a mesma interface. Quem carrega por último ganha, e essa ordem sai do sequence declarado no module.xml.