Erro 1062 MySQL: Duplicate entry, como resolver

Entenda o erro 1062 do MySQL, ache a linha e o índice que repetem o valor e escolha entre ON DUPLICATE KEY UPDATE, INSERT IGNORE e REPLACE.

Por Redação Eleven Host · @robson.direitodigital · 29 de outubro de 2026 · 9 min de leitura

O erro 1062 MySQL, "Duplicate entry", aparece quando você tenta gravar um valor que já existe numa coluna que não aceita repetição. Segundo o manual do MySQL 8.4, isso acontece numa PRIMARY KEY ou num índice UNIQUE.

Este guia explica o que a mensagem diz, como achar a linha que já existe, como descobrir qual índice barrou a gravação e quais são as três saídas que o manual descreve: ON DUPLICATE KEY UPDATE, INSERT IGNORE e REPLACE. Os fatos sobre o erro e sobre essas três instruções vêm do manual do MySQL 8.4. Os comandos de diagnóstico são práticas comuns de administração. Os exemplos usam nomes fictícios, como a tabela clientes e o e-mail maria@exemplo.com.

O que o erro 1062 significa

No manual do MySQL, o erro 1062 tem o símbolo ER_DUP_ENTRY, o SQLSTATE 23000 e a mensagem Duplicate entry '%s' for key %d. Na prática, o servidor troca os marcadores pelo valor repetido e pelo nome do índice. Um exemplo do próprio manual:

ERROR 1062 (23000): Duplicate entry '1' for key 't.b'

Lendo a mensagem de trás para frente: t.b é o índice que barrou a gravação, e 1 é o valor que já existia nele. A frase em português simples é: "você tentou gravar o valor 1, mas o índice t.b só aceita cada valor uma vez, e o 1 já está lá".

O erro não diz que a sua sintaxe está errada nem que o banco caiu. Ele aponta um valor repetido.

Quando o erro acontece

O manual descreve a causa técnica: o valor se repete numa PRIMARY KEY ou num índice UNIQUE. Do ponto de vista de quem administra um site ou um sistema, alguns cenários podem levar a isso:

• Formulário enviado duas vezes: a pessoa clica duas vezes no botão e a mesma linha chega duas vezes.
• Importação repetida de um backup: o arquivo SQL é importado de novo e as linhas que já estão na tabela voltam a ser inseridas.
• Cadastro com e-mail que já existe: se a coluna de e-mail tem índice UNIQUE, o segundo cadastro com o mesmo e-mail é recusado.
• Valor de chave informado à mão: um id escrito no INSERT que já pertence a outra linha.

Essa lista é de situações comuns de uso, não do manual. O que o manual garante é a regra: repetiu valor numa PRIMARY KEY ou UNIQUE, o erro 1062 pode aparecer.

Passo 1: ache a linha que já existe

A mensagem entrega o valor repetido. Procure a linha que o guarda. Se o erro foi Duplicate entry 'maria@exemplo.com' for key 'clientes.email', rode:

SELECT * FROM clientes WHERE email = 'maria@exemplo.com';

Compare a linha encontrada com a que você tentou gravar. Duas respostas são possíveis:

• As duas são o mesmo registro. Então a gravação era mesmo repetida, e o certo pode ser atualizar a linha existente ou simplesmente ignorar a nova.
• São registros diferentes que disputam o mesmo valor. Então o problema pode estar nos dados (dois clientes com o mesmo e-mail) ou na regra da tabela.

Passo 2: descubra qual índice barrou a gravação

O nome depois de for key é o do índice. Para ver todos os índices da tabela, use um destes comandos:

SHOW INDEX FROM clientes;

SHOW CREATE TABLE clientes;

Procure o índice com o nome da mensagem. Se Non_unique for 0, o índice é único. O SHOW CREATE TABLE mostra a mesma informação na forma de definição da tabela, com PRIMARY KEY e UNIQUE KEY.

Esse passo importa porque uma tabela pode ter vários índices únicos. O erro cita só um deles: o que foi violado. Resolver o conflito nesse índice e rodar de novo pode revelar outro conflito, em outro índice.

Se o banco está numa VPS que você administra e o acesso ao mysql ainda é novidade, o guia completo de servidor VPS explica o que é uma VPS.

Precisa de um banco de dados? O 11SQL Mini sai a partir de R$ 9,90/mês; confira na loja o que cada plano inclui. Ver planos de banco de dados

Passo 3: escolha como tratar a duplicata

O manual do MySQL descreve três formas de lidar com uma linha que repete uma PRIMARY KEY ou UNIQUE. Cada uma faz uma coisa diferente, e a escolha depende do que você quer que aconteça com a linha antiga e com a nova.

ON DUPLICATE KEY UPDATE: atualizar a linha existente

Segundo o manual, com ON DUPLICATE KEY UPDATE, se a linha nova duplicar uma PRIMARY KEY ou UNIQUE, ocorre uma atualização (UPDATE) da linha antiga. O exemplo do manual:

INSERT INTO t1 (a,b,c) VALUES (1,2,3)

ON DUPLICATE KEY UPDATE c=c+1;

Com a coluna a sendo única, o efeito é parecido com este:

UPDATE t1 SET c=c+1 WHERE a=1;

O manual dá mais três detalhes úteis:

• Linhas afetadas: o valor é 1 quando a linha foi inserida, 2 quando foi atualizada e 0 quando a linha já tinha exatamente esses valores.
• Auto-incremento no InnoDB: o INSERT aumenta o valor do auto-incremento, e o UPDATE não.
• Forma recomendada: usar um alias para a linha nova, porque a função VALUES() está obsoleta.

A forma com alias, do manual:

INSERT INTO t1 (a,b,c) VALUES (1,2,3),(4,5,6) AS new

ON DUPLICATE KEY UPDATE c = new.a+new.b;

O manual também faz um aviso: evite ON DUPLICATE KEY UPDATE em tabelas com vários índices únicos. Se a sua tabela tem mais de um, confira os índices (passo 2) antes de usar essa opção.

INSERT IGNORE: pular a linha duplicada

Com INSERT IGNORE, o erro vira um aviso (warning) e a execução continua. A linha duplicada é descartada. Para ver o aviso, rode SHOW WARNINGS:

SHOW WARNINGS;

-- Warning | 1062 | Duplicate entry '1' for key 't.b'

O resumo da execução vem no formato Records: N1 Duplicates: N2 Warnings: N3. Em uma carga de muitas linhas, o número de Duplicates diz quantas foram descartadas.

Use essa opção quando descartar a repetida é o que você quer, como numa importação em que parte das linhas já está na tabela. Confira o resumo para saber quantas linhas foram descartadas.

REPLACE: apagar a antiga e inserir a nova

O REPLACE funciona como o INSERT, com uma diferença: se uma linha antiga tiver o mesmo valor de PRIMARY KEY ou UNIQUE que a nova, a antiga é apagada antes de a nova ser inserida. Um resultado maior que 1 nas linhas afetadas indica que linhas antigas foram apagadas. Para usar o REPLACE, a conta precisa dos privilégios INSERT e DELETE. Numa tabela sem PRIMARY KEY nem UNIQUE, ele equivale a um INSERT.

REPLACE INTO clientes (id, email) VALUES (7, 'maria@exemplo.com');

Atenção: aqui a linha antiga é apagada e uma nova é inserida. Se você só queria mudar uma coluna, o ON DUPLICATE KEY UPDATE descreve melhor a intenção.

Qual das três usar

• Quer atualizar a linha que já existe? Use ON DUPLICATE KEY UPDATE.
• Quer pular as repetidas e seguir adiante? Use INSERT IGNORE, e confira o resumo e o SHOW WARNINGS.
• Quer que a linha nova substitua a antiga? Use REPLACE, sabendo que a antiga é apagada.
• A repetição é um erro de dados? Corrija o dado e não esconda o problema com uma das três opções.

Erro 1062 ao importar um backup

Quando o 1062 aparece no meio de uma importação, o arquivo SQL pode estar tentando inserir linhas que já estão na tabela. Isso pode ocorrer quando o mesmo backup é importado duas vezes ou quando a importação foi interrompida e retomada do começo. O guia Importar banco de dados MySQL: passo a passo e erros comuns mostra o processo de importação inteiro. Para gerar o arquivo em primeiro lugar, veja Backup MySQL com mysqldump: como fazer e restaurar.

Antes de importar de novo numa tabela que já tem dados, faça uma cópia do estado atual. Assim você pode voltar atrás se a escolha entre pular, atualizar ou substituir não der o resultado esperado.

Como evitar o erro no futuro

• Deixe o banco gerar o id: com uma coluna de auto-incremento, você não precisa escrever o valor da chave à mão.
• Valide antes de gravar: no cadastro, procure o e-mail com um SELECT e avise a pessoa, em vez de deixar o erro chegar à tela.
• Bloqueie o clique duplo: desligue o botão de envio depois do primeiro clique.
• Escolha a instrução conforme a intenção: atualizar, pular e substituir são decisões diferentes.
• Trate o erro na aplicação: capture o erro 1062 e mostre uma mensagem clara, como "este e-mail já está cadastrado".

Se a sua consulta nem chega a rodar por causa da escrita do comando, veja Erro 1064 MySQL: erro de sintaxe SQL, como resolver. Se o erro for de tabela inexistente, o guia certo é Erro 1146 MySQL: tabela não existe, como resolver.

Quer administrar o seu próprio servidor de banco? O Plano Bronze da VPS sai a partir de R$ 17,00/mês; confira na loja o que o plano inclui. Ver planos de VPS

Perguntas frequentes

O que significa Duplicate entry no MySQL?

Significa que o valor que você tentou gravar já existe numa coluna com PRIMARY KEY ou índice UNIQUE. O MySQL recusa a gravação com o erro 1062 (SQLSTATE 23000).

Como achar a linha que causou o erro 1062?

Use o valor da mensagem num SELECT ... WHERE coluna = 'valor';. Para saber qual índice foi violado, use SHOW INDEX FROM tabela; ou SHOW CREATE TABLE tabela;.

Qual a diferença entre INSERT IGNORE e REPLACE?

Com INSERT IGNORE, o erro vira aviso e a linha duplicada é descartada. Com REPLACE, se a linha antiga tiver o mesmo valor de PRIMARY KEY ou UNIQUE, ela é apagada antes de a nova ser inserida.

O que significa o número de linhas afetadas no ON DUPLICATE KEY UPDATE?

Segundo o manual, 1 indica linha inserida, 2 indica linha atualizada e 0 indica que a linha já tinha esses valores.

Posso usar ON DUPLICATE KEY UPDATE em tabelas com vários índices únicos?

O manual avisa para evitar o uso nesse caso. Se a sua tabela tem mais de um índice único, confira os índices antes e avalie outra opção.