Solucionar error de clave duplicada en base de datos PrestaShop

El error de clave duplicada, habitualmente reportado como Duplicate entry 'X' for key 'PRIMARY', ocurre cuando PrestaShop intenta insertar un registro en la base de datos que ya existe o cuyo identificador (ID) ya está ocupado. La solución pasa por resetear los autoincrementos de las tablas afectadas o limpiar los registros huérfanos que bloquean la inserción.

Qué significa el error

Este mensaje aparece durante procesos de importación masiva mediante CSV o al migrar datos entre tiendas. Indica que el sistema de gestión de base de datos (MySQL o MariaDB) ha intentado escribir una fila con un ID que ya existe en la tabla correspondiente. El proceso se detiene inmediatamente para evitar la corrupción de datos. Afecta principalmente a los administradores de tiendas que gestionan catálogos grandes o importan pedidos externos y bloquea la continuidad de la operación de escritura en tablas como ps_orders, ps_order_detail o ps_product.

Causas más habituales

• Desincronización del contador AUTO_INCREMENT en la tabla de destino.
• Importación de archivos CSV con IDs que ya existen en la base de datos actual.
• Interrupción de una importación previa que dejó registros parciales pero incrementó el contador de ID.
• Uso de módulos de migración que no gestionan correctamente los IDs existentes.
• Conflictos de claves foráneas (Foreign Keys) al intentar relacionar tablas con IDs inconsistentes.

Antes de empezar

Cualquier manipulación directa de la base de datos conlleva riesgos. Sigue estos pasos obligatorios: realiza una copia de seguridad completa de la base de datos mediante mysqldump o la herramienta de exportación de tu panel de hosting (cPanel o Plesk). Asegúrate de tener acceso a phpMyAdmin o a la consola de comandos de MySQL. Verifica que tu usuario de base de datos tiene permisos ALTER y UPDATE sobre las tablas. Esta guía asume un entorno con PHP 7.4 o superior y MySQL 5.7 o MariaDB 10.x.

Solución 1: Resetear el autoincremento de la tabla

Esta es la solución más frecuente cuando el contador de la base de datos se ha quedado por debajo del ID real más alto existente. Al insertar un nuevo registro, el sistema intenta usar un ID que ya está ocupado.

1. Accede a phpMyAdmin y selecciona tu base de datos de PrestaShop.
2. Localiza la tabla que genera el error (por ejemplo, ps_orders).
3. Haz clic en la pestaña Operaciones.
4. Busca la sección AUTO_INCREMENT.
5. Introduce un valor superior al ID más alto que aparece actualmente en la tabla (puedes verificarlo ejecutando SELECT MAX(id_order) FROM ps_orders;).
6. Haz clic en Continuar.

Al forzar el autoincremento a un valor superior al máximo existente, MySQL asignará automáticamente el siguiente ID disponible sin colisionar con los registros anteriores, permitiendo que la importación continúe.

Solución 2: Eliminar registros duplicados manualmente

Si la importación falló a mitad de proceso, es posible que existan registros parciales con IDs que intentan volver a escribirse. Debes limpiar la tabla antes de reintentar.

1. Identifica el ID que causa el conflicto en el mensaje de error (ejemplo: Duplicate entry '1234').
2. Ejecuta la siguiente consulta SQL en la pestaña SQL de phpMyAdmin: DELETE FROM ps_orders WHERE id_order = 1234;.
3. Si el error persiste en tablas relacionadas como ps_order_detail, repite el proceso eliminando las filas con el mismo ID de pedido.
4. Limpia la caché de PrestaShop desde el Panel de Administración en Parámetros Avanzados > Rendimiento.

Esta acción elimina el registro que impide la inserción. Es fundamental borrar también las entradas en las tablas dependientes para mantener la integridad referencial. Si necesitas más ayuda con la gestión de caché, consulta nuestra guía sobre cómo solucionar el error SmartyCompilerException en PrestaShop.

Solución 3: Ajustar el archivo CSV de importación

A menudo, el error no está en la base de datos, sino en el archivo CSV que contiene IDs definidos manualmente que ya existen en el sistema.

1. Abre tu archivo CSV con un editor de texto plano o Excel.
2. Revisa la columna que contiene los IDs (por ejemplo, id_order o id_product).
3. Elimina la columna de ID si no es estrictamente necesario mantener los números originales; PrestaShop asignará nuevos IDs automáticamente.
4. Si debes mantener los IDs, asegúrate de que no hay duplicados dentro del propio archivo CSV.
5. Guarda el archivo en formato UTF-8 sin BOM.
6. Vuelve a intentar la importación desde el panel de control.

Al eliminar la columna de ID, obligas a PrestaShop a generar nuevos identificadores, eliminando cualquier posibilidad de conflicto con los registros existentes. Si el proceso sigue fallando por tiempos de ejecución, revisa nuestra guía sobre cómo solucionar el error de tiempo de espera agotado al importar CSV en PrestaShop.

Solución 4: Reparar tablas corruptas

A veces, el error es consecuencia de una tabla marcada como corrupta o con índices dañados tras una importación fallida.

1. En phpMyAdmin, selecciona la tabla afectada.
2. En la parte inferior de la lista de tablas, selecciona la opción Reparar tabla en el menú desplegable.
3. Alternativamente, ejecuta el comando: REPAIR TABLE ps_orders;.
4. Espera a que el proceso termine; MySQL reconstruirá los índices de la tabla.

La reparación de tablas soluciona inconsistencias en los índices primarios que pueden hacer que MySQL crea erróneamente que un ID está duplicado cuando no lo está. Es un proceso seguro que no borra datos, solo reconstruye la estructura interna de los índices.

Cómo comprobar que se ha solucionado

Tras aplicar cualquiera de las soluciones, intenta realizar la importación nuevamente con un archivo CSV pequeño (de 5 a 10 filas) para verificar el funcionamiento. Si el proceso finaliza sin mensajes de error, intenta con el archivo completo. Comprueba en el panel de administración, en la sección correspondiente (Pedidos o Catálogo), que los registros se visualizan correctamente y no presentan errores al abrirse. Si los datos aparecen, la integridad de la base de datos está restaurada.

Si nada de lo anterior funciona

Si tras aplicar estas soluciones el error persiste, es probable que exista una corrupción profunda en la estructura de la base de datos o un conflicto de módulos. Revisa los logs de errores de PHP en tu servidor, generalmente ubicados en /var/log/apache2/error.log o dentro de la carpeta /var/logs/ de tu instalación de PrestaShop. Busca entradas que mencionen SQLSTATE. Si el problema persiste, contacta con el desarrollador del módulo de importación que estás utilizando o solicita asistencia técnica especializada, ya que podría requerir una intervención manual sobre la estructura de claves foráneas de la base de datos.

Preguntas frecuentes

¿Es seguro borrar registros manualmente en la base de datos?

Es seguro siempre que sepas exactamente qué registro estás borrando y hayas realizado una copia de seguridad previa. Nunca elimines filas de tablas de configuración o de módulos sin verificar antes su dependencia.

¿Por qué mi ID de pedido en el CSV no coincide con el de la tienda?

PrestaShop utiliza su propio sistema de autoincremento. Si importas un CSV con IDs, el sistema intenta respetarlos, pero si ya existen, el proceso fallará. Lo ideal es dejar que el sistema genere los IDs nuevos durante la importación.

¿Debo desactivar los módulos antes de importar?

Sí, es recomendable desactivar módulos de terceros que actúen sobre los pedidos o productos (como módulos de facturación o sincronización externa) durante la importación para evitar que intenten procesar registros a medio escribir.

¿Cómo sé qué tabla está causando el error?

El mensaje de error suele incluir el nombre de la tabla después de la cláusula INTO o al final del mensaje de error, por ejemplo: Duplicate entry for key 'PRIMARY' table 'ps_orders'.