Como Resolver o Erro de Entity Tracking no Entity Framework Core

Se você trabalha com Entity Framework Core, existe um erro que costuma aparecer justamente quando parece que estamos fazendo algo simples: atualizar uma entidade.

The instance of entity type 'Produto' cannot be tracked because another instance with the same key value for {'Id'} is already being tracked.

A primeira reação costuma ser olhar para o SaveChanges() e tentar descobrir o que está acontecendo ali.

Mas, na maioria das vezes, o problema começou antes.

O Entity Framework Core já está acompanhando uma instância daquela entidade e, em algum momento do fluxo, outra instância com a mesma chave chega ao mesmo DbContext.

Foi exatamente esse tipo de situação que encontrei durante o desenvolvimento de uma API de rastreamento logístico.

Onde encontrei esse problema

Na época, eu estava implementando uma API para um sistema de rastreamento de logística.

O fluxo era, de forma simplificada, o seguinte: o CRM fazia uma requisição POST para a API, e a API recebia os acontecimentos relacionados à jornada de um chip até o cliente final.

Não era apenas uma informação de "entregue" ou "não entregue".

A API precisava receber e processar diferentes etapas da jornada, como:

Chip enviado
    ?
Chip entregue à transportadora
    ?
Caminhão em trânsito
    ?
Objeto em rota de entrega
    ?
Cliente não encontrado na residência
    ?
Nova tentativa de entrega
    ?
Entrega realizada

Cada acontecimento precisava ser registrado para que o sistema pudesse acompanhar a situação daquele produto.

Foi justamente nesse fluxo que apareceu o problema.

A entidade Produto estava envolvida no processamento e, quando determinada etapa era recebida, também era necessário atualizar o histórico de auditoria para registrar o status correspondente àquela fase da entrega.

Em determinado momento desse processo, o Entity Framework Core já estava acompanhando uma instância de Produto, enquanto outra instância representando o mesmo registro acabava sendo utilizada dentro daquele mesmo DbContext.

Foi aí que apareceu o erro de Entity Tracking.

Na época, a solução foi conduzida utilizando uma API que já existia no projeto e que permitiu implementar a regra de forma diferente. A correção funcionou.

Como o código original desse projeto não está mais disponível, não vou fingir que lembro exatamente cada linha da implementação ou apresentar aquele código como se fosse o código original.

O objetivo deste artigo é outro: explicar o problema que reconheci naquela situação e mostrar como entender e resolver esse tipo de conflito no Entity Framework Core.

O que é o Entity Tracking?

O Entity Framework Core possui um mecanismo chamado Change Tracker.

Ele acompanha as entidades que estão sendo utilizadas pelo DbContext para saber o que mudou e, posteriormente, transformar essas alterações em operações no banco de dados.

Por exemplo:

var produto = await context.Produtos
    .FirstOrDefaultAsync(x => x.Id == 10);

Em uma consulta normal com tracking, o EF Core passa a acompanhar a instância retornada.

Podemos imaginar:

DbContext
   ¦
   +-- Produto
        +-- Id = 10

Se alterarmos essa mesma instância:

produto.Nome = "Novo nome";
produto.Preco = 99.90m;

await context.SaveChangesAsync();

o EF Core consegue identificar as alterações e gerar o UPDATE correspondente.

Até aqui, tudo bem.

O problema aparece quando tentamos fazer o mesmo DbContext acompanhar outra instância que representa a mesma entidade e possui a mesma chave primária.

O que significa "outra instância"?

Imagine que o contexto já carregou:

var produto = await context.Produtos
    .FirstOrDefaultAsync(x => x.Id == 10);

Agora criamos outro objeto:

var outroProduto = new Produto
{
    Id = 10,
    Nome = "Produto atualizado",
    Preco = 99.90m
};

Para o C#, são dois objetos diferentes.

produto
Id = 10

outroProduto
Id = 10

Mas, para o Entity Framework Core, ambos representam a mesma entidade do banco.

O DbContext não pode simplesmente decidir qual dos dois objetos deve representar o registro Id = 10.

Qual nome deveria ser utilizado?

Qual preço?

Qual relacionamento?

Qual estado?

Por isso existe o conceito de Identity Resolution.

Um determinado DbContext só pode rastrear uma instância de uma entidade para uma determinada chave primária.

Como o erro acontece na prática

Um exemplo simples seria:

var produto = await context.Produtos
    .FirstOrDefaultAsync(x => x.Id == 10);

var outroProduto = new Produto
{
Id = 10,
Nome = "Produto atualizado"
};

context.Update(outroProduto);

await context.SaveChangesAsync();

Nesse cenário, o contexto já está acompanhando produto.

Depois tentamos colocar outroProduto, que também possui Id = 10, no mesmo contexto.

É justamente nesse momento que o Entity Framework Core pode lançar a exceção:

The instance of entity type 'Produto' cannot be tracked because another instance with the same key value is already being tracked.

O problema, portanto, não é simplesmente existirem dois objetos C# com o mesmo Id.

O problema é tentar fazer o mesmo DbContext acompanhar duas instâncias que representam a mesma entidade.

Por que o Entity Framework Core não permite isso?

Pode parecer uma limitação desnecessária, mas existe uma razão.

Imagine que o contexto estivesse acompanhando:

Produto A
Id = 10
Nome = "Produto A"
Preço = 50

e também:

Produto B
Id = 10
Nome = "Produto B"
Preço = 100

Qual desses valores deveria ser enviado para o banco?

O EF Core teria que decidir qual objeto representa a versão correta da entidade.

A mesma ambiguidade pode acontecer com relacionamentos entre entidades.

Por isso o EF Core mantém uma única instância rastreada para determinada chave dentro do contexto.

Uma situação muito comum em APIs

Esse problema aparece bastante quando trabalhamos com APIs porque normalmente recebemos dados de uma requisição e precisamos transformá-los em entidades.

Imagine uma requisição como:

{
    "id": 10,
    "nome": "Produto atualizado",
    "preco": 99.90
}

O objeto recebido pela API pode ser diferente da entidade que já foi carregada pelo DbContext.

Temos então:

Requisição HTTP
      ?
Objeto recebido
      ?
Produto Id = 10

```
         +
```

Banco de dados
?
Entidade carregada
?
Produto Id = 10

Se essas duas instâncias forem colocadas para serem rastreadas pelo mesmo contexto, temos o cenário clássico do erro.

Foi justamente esse tipo de situação que tornou o problema que encontrei no projeto de rastreamento logístico interessante para mim.

O erro não estava simplesmente em "atualizar um produto".

Ele estava relacionado ao estado das entidades dentro daquele fluxo de processamento.

Solução 1: trabalhar com a entidade que já está sendo rastreada

Quando temos uma entidade existente no banco, uma das abordagens mais simples é carregar a entidade e modificar a própria instância retornada pelo contexto.

Por exemplo:

var produto = await context.Produtos
    .FirstOrDefaultAsync(x => x.Id == id);

if (produto == null)
{
return;
}

produto.Nome = "Novo nome";
produto.Preco = 99.90m;

await context.SaveChangesAsync();

Aqui existe apenas uma instância de Produto sendo acompanhada pelo contexto.

O fluxo fica:

Banco
 ?
Produto
 ?
DbContext acompanha a entidade
 ?
Alteramos os valores
 ?
SaveChanges()
 ?
UPDATE

Para muitos cenários de atualização, essa é uma abordagem simples e previsível.

Solução 2: copiar os valores para a entidade rastreada

Existem situações em que temos um objeto recebido pela API e uma entidade correspondente já carregada pelo contexto.

Nesse caso, podemos copiar os valores do objeto recebido para a entidade que já está sendo rastreada.

Por exemplo:

var produto = await context.Produtos
    .FirstOrDefaultAsync(x => x.Id == produtoAtualizado.Id);

if (produto == null)
{
return;
}

context.Entry(produto)
.CurrentValues
.SetValues(produtoAtualizado);

await context.SaveChangesAsync();

A ideia é importante:

produtoAtualizado
       ¦
       ¦ SetValues()
       ?
produto já rastreado
       ¦
       ?
SaveChanges()

Não estamos tentando colocar uma segunda instância de Produto no contexto.

Estamos atualizando a instância que o contexto já conhece.

O SetValues() é especialmente útil para copiar valores de propriedades escalares. Ele não deve ser entendido como uma solução automática para sincronizar todo um grafo de entidades e relacionamentos.

Se existirem entidades relacionadas, elas precisam ser tratadas de acordo com o cenário.

Solução 3: atualizar somente a chave estrangeira quando for suficiente

Outro cenário bastante comum envolve entidades relacionadas.

Imagine:

public class Produto
{
    public int Id { get; set; }
    public string Nome { get; set; }

```
public int CategoriaId { get; set; }
public Categoria Categoria { get; set; }
```

}

Se precisamos apenas mudar a categoria do produto, talvez não seja necessário criar uma nova instância de Categoria.

Podemos simplesmente alterar a chave estrangeira:

produto.CategoriaId = novaCategoriaId;

Isso é diferente de fazer:

produto.Categoria = new Categoria
{
    Id = novaCategoriaId
};

A segunda abordagem introduz outra instância de Categoria no grafo de entidades.

Dependendo do que já estiver sendo rastreado pelo contexto, isso pode criar mais uma situação de conflito.

Se tudo que precisamos informar é:

"Este produto agora pertence à categoria 5."

então muitas vezes:

produto.CategoriaId = 5;

é suficiente.

Solução 4: AsNoTracking() para consultas que não precisam ser alteradas

Outra ferramenta importante do EF Core é:

AsNoTracking()

Por exemplo:

var produto = await context.Produtos
    .AsNoTracking()
    .FirstOrDefaultAsync(x => x.Id == id);

Nesse caso, o EF Core não mantém aquela entidade no Change Tracker da maneira que uma consulta normal com tracking faria.

Essa abordagem é bastante útil para consultas que serão utilizadas apenas para leitura.

Por exemplo:

var produtos = await context.Produtos
    .AsNoTracking()
    .ToListAsync();

Se a finalidade da consulta é simplesmente retornar dados para uma tela ou resposta de API, não existe necessariamente motivo para manter todas aquelas entidades sendo rastreadas.

Mas cuidado

AsNoTracking() não é uma solução genérica para qualquer erro de Entity Tracking.

Eu não recomendo pensar:

"Deu erro de Entity Tracking? Vou colocar AsNoTracking()."

Isso pode simplesmente esconder o problema ou criar outro.

Se você precisa:

1. consultar uma entidade;
2. modificar essa entidade;
3. chamar SaveChanges();

o tracking pode ser exatamente o comportamento que você precisa.

Por isso, antes de utilizar essa opção, pergunte:

Essa consulta realmente precisa ser rastreada?

Se a resposta for não, AsNoTracking() pode fazer sentido.

Solução 5: verificar o tempo de vida do DbContext

Essa é uma parte que merece bastante atenção.

O DbContext não foi projetado para viver indefinidamente.

Ele representa normalmente uma unidade de trabalho: criar o contexto, consultar ou anexar entidades, fazer as alterações, executar SaveChanges() e então encerrar aquele contexto.

Um problema comum é reutilizar a mesma instância por tempo demais.

Imagine:

Request 1
   ?
DbContext
   ?
Produto Id = 10
   ?
continua vivo...

Request 2
?
mesmo DbContext
?
Produto Id = 10

Quanto mais tempo o mesmo contexto permanece vivo, maior pode ficar a quantidade de entidades que ele está acompanhando.

Em uma API, isso merece atenção especial.

Em aplicações ASP.NET Core utilizando injeção de dependência, o padrão comum é registrar o DbContext para uma unidade de trabalho associada à requisição.

Portanto, antes de começar a colocar Detach, AsNoTracking() ou outras soluções espalhadas pelo código, vale perguntar:

Meu DbContext está sendo utilizado pelo tempo correto?

Se o contexto estiver sendo compartilhado entre diferentes operações que deveriam ser independentes, o problema pode estar na arquitetura do fluxo e não naquela entidade específica.

Como descobrir o que o DbContext está rastreando?

Quando o erro não é óbvio, uma das ferramentas mais úteis é olhar o próprio Change Tracker.

Podemos fazer:

var entidades = context.ChangeTracker
    .Entries()
    .ToList();

Durante uma investigação, isso permite verificar quais entidades estão sendo acompanhadas naquele momento.

Por exemplo, imagine encontrar algo semelhante a:

Produto    Id = 10    Modified
Categoria  Id = 5     Unchanged
Produto    Id = 10    Added

Agora temos uma pista muito mais concreta.

Existe mais de uma instância de Produto com a mesma chave tentando participar do tracking daquele contexto.

Essa investigação costuma ser muito mais útil do que simplesmente tentar uma solução aleatória.

E o Detach?

Também é possível remover uma entidade do tracking:

context.Entry(produtoExistente).State =
    EntityState.Detached;

Depois disso, outra instância pode ser anexada ou atualizada.

Por exemplo:

context.Entry(produtoExistente).State =
    EntityState.Detached;

context.Update(produtoAtualizado);

await context.SaveChangesAsync();

Isso pode ser útil em situações específicas.

Mas eu não trataria Detach() como a primeira solução para um erro de Entity Tracking.

O motivo é que precisamos entender exatamente o que está sendo removido do tracking e quais entidades fazem parte do grafo que será anexado novamente.

Em outras palavras:

Detach() pode resolver o sintoma sem necessariamente resolver a causa.

Antes de utilizá-lo, vale investigar por que duas instâncias chegaram ao mesmo DbContext.

E o EnableSensitiveDataLogging()?

Durante uma investigação em ambiente de desenvolvimento, também podemos habilitar:

optionsBuilder
    .EnableSensitiveDataLogging();

Isso pode fornecer informações adicionais nos logs e ajudar a identificar os valores envolvidos no problema.

Mas é importante ter cuidado.

Essa opção pode fazer informações potencialmente sensíveis aparecerem nos logs. Portanto, não é algo que eu recomendaria deixar habilitado indiscriminadamente em produção.

Use principalmente durante o diagnóstico e de maneira controlada.

Então, qual solução devo usar?

Não existe uma solução universal.

O primeiro passo deve ser descobrir por que duas instâncias da mesma entidade estão chegando ao mesmo DbContext.

Depois disso, a solução fica muito mais clara.

O mais importante é não escolher uma dessas alternativas simplesmente porque ela fez a exceção desaparecer.

Primeiro entenda o fluxo das entidades. Depois escolha a abordagem adequada.

O que eu aprendi com esse problema

O interessante desse tipo de erro é que ele pode parecer completamente desconectado da causa real.

Você está processando um evento.

Precisa atualizar uma informação.

Chama o SaveChanges().

E de repente recebe uma exceção dizendo que uma entidade já está sendo rastreada.

Foi exatamente esse tipo de situação que encontrei naquela API de rastreamento.

O sistema precisava processar os eventos da jornada do chip e atualizar o histórico de auditoria correspondente à etapa da entrega. O problema apareceu envolvendo a entidade Produto, dentro desse fluxo.

Na época, a solução que me apresentaram funcionou e o desenvolvimento continuou.

Hoje, olhando para aquele problema com mais conhecimento sobre o funcionamento do Entity Framework Core, fica mais fácil entender o que estava acontecendo por trás da exceção.

O ponto principal é que o Entity Framework não está simplesmente reclamando porque existem dois objetos iguais.

Ele está tentando evitar uma situação em que o mesmo DbContext tenha duas representações diferentes da mesma entidade.

Por isso, quando esse erro aparecer, minha primeira pergunta seria:

Qual instância dessa entidade o meu DbContext já está rastreando?

Depois:

Por que meu código está tentando trabalhar com outra instância da mesma entidade?

Essas duas perguntas normalmente levam muito mais rápido à causa do problema do que simplesmente sair adicionando AsNoTracking(), Detach() ou Update() até a exceção desaparecer.

E essa, para mim, é a principal lição do Entity Tracking: não tente apenas fazer o erro desaparecer. Entenda o que o DbContext está rastreando e por quê.