Cómo solucionar una clave primaria faltante en la tabla wp_options de WordPress

Resumen: La falta de una clave primaria en la tabla wp_options significa que MySQL deja de incrementar automáticamente option_id, por lo que las nuevas filas se escriben con option_id = 0. WordPress sigue funcionando, pero cada exportación, migración o publicación de staging falla con un error de clave duplicada, y las consultas contra la tabla se vuelven más lentas porque MySQL ya no puede usar la clave. La solución más rápida: haz una copia de seguridad de la base de datos, renumera los valores option_id duplicados para que cada uno sea único, luego ejecuta ALTER TABLE wp_options ADD PRIMARY KEY (option_id) y restaura AUTO_INCREMENT. Puedes hacer toda la reparación en phpMyAdmin o con SQL puro, y no se requiere ningún plugin.

A veces, bajo ciertas circunstancias, la tabla wp_options (o cualquier otra tabla) puede perder su índice de clave primaria. El desencadenante exacto rara vez es evidente. En los tickets de soporte de WP STAGING, lo vemos con mayor frecuencia en bases de datos que fueron migradas manualmente de un servidor a otro, o movidas con una herramienta que no contempló todos los casos, como un cambio entre versiones de MySQL o entre los motores de almacenamiento InnoDB y MyISAM.

Para dejarlo claro: WP STAGING no es la causa de este error. WP STAGING solo te ayuda a detectarlo, mostrando una advertencia destacada en tu panel de administración de WordPress cuando encuentra una tabla principal sin clave primaria. Lo sacamos a la luz pronto porque se trata de un problema crítico e insidioso. Tu sitio sigue cargándose como si nada estuviera mal, así que no lo notarás hasta que falle una migración o una copia de seguridad, y para entonces la tabla puede contener cientos de filas dañadas. Cuanto más tiempo se deja sin corregir, más filas duplicadas se acumulan y más trabajo supone la reparación.

Qué es una clave primaria y por qué wp_options necesita una

Una clave primaria es una columna (o un conjunto de columnas) que identifica de forma única cada fila de una tabla. En una instalación estándar de WordPress, la tabla wp_options usa option_id como su clave primaria. option_id está definida como bigint(20) unsigned NOT NULL auto_increment, lo que significa que la base de datos asigna a cada nueva fila el siguiente número no utilizado automáticamente y garantiza que no haya dos filas que compartan el mismo valor.

Dos cosas se rompen cuando esa clave desaparece:

• El autoincremento se detiene. Sin la clave primaria, MySQL ya no incrementa option_id. Cada nueva fila se inserta con el valor por defecto 0. El ejemplo original a continuación muestra cómo es una secuencia sana:Y así es como se ve la misma columna una vez que la clave ha desaparecido y las nuevas filas se acumulan con option_id = 0:
• Las exportaciones y migraciones fallan. Una columna de clave primaria debe contener valores únicos. En el momento en que exportas estas filas y las importas a otra base de datos, MySQL rechaza los duplicados con un error como Cannot insert duplicate key, y la importación se detiene a medio camino. Por eso WP STAGING y cualquier otro plugin de migración no pueden completar una transferencia de base de datos cuando falta la clave. La publicación de un sitio de staging a producción falla exactamente en el punto en que se escriben las filas 0 duplicadas.

También hay un coste más silencioso. wp_options es una de las tablas más leídas de WordPress, porque las opciones de autocarga se obtienen en casi cada petición. En nuestras pruebas, la falta de una clave primaria obliga a MySQL a recurrir a un escaneo completo de la tabla para búsquedas que de otro modo usarían la clave, lo que añade una sobrecarga medible a las cargas de página normales. Si quieres conocer el contexto de cómo encaja wp_options en el esquema más amplio, consulta nuestra guía sobre las tablas esenciales de la base de datos de WordPress.

Cómo confirmar que la clave primaria realmente falta

Antes de cambiar nada, confirma que este es realmente tu problema. Abre una herramienta de base de datos como phpMyAdmin o Adminer, selecciona tu base de datos de WordPress y ejecuta:

SHOW CREATE TABLE wp_options;

En una tabla sana, la salida contiene una línea como PRIMARY KEY (option_id) y la columna option_id está marcada como AUTO_INCREMENT. Si faltan ambas, la clave ha desaparecido. También puedes listar los índices directamente:

SHOW INDEX FROM wp_options;

Una tabla con una clave intacta devuelve una fila donde Key_name es PRIMARY. Si esa fila está ausente, no hay clave primaria.

Esta captura muestra una tabla wp_options normal con una clave primaria establecida en la columna option_id:

Esta segunda captura muestra la misma tabla con la clave primaria faltante:

Para ver cuántas filas ya están afectadas, cuenta los duplicados:

SELECT option_id, COUNT(*) AS copies
FROM wp_options
GROUP BY option_id
HAVING copies > 1;

Cualquier grupo con option_id = 0 y un recuento superior a uno confirma las filas dañadas que necesitas renumerar antes de poder restaurar la clave.

Reemplaza wp_options con el nombre real de tu tabla en todo momento si tu instalación usa un prefijo de tabla personalizado (por ejemplo wp_xyz_options).

Antes de empezar: haz una copia de seguridad de la base de datos

Cada paso a continuación modifica la base de datos directamente, así que haz una copia de seguridad completa primero y descárgala fuera del servidor. Si algo sale mal, querrás tener una copia limpia para restaurar. Una copia de seguridad de WP STAGING, una exportación de phpMyAdmin o un mysqldump son todas válidas. Este es también un buen momento para hacer el trabajo en una copia de staging en lugar de en producción: clona el sitio, repara la tabla allí, confirma el resultado y solo entonces aplica la misma corrección a la base de datos en vivo.

Corregir la clave primaria faltante en phpMyAdmin

Si prefieres una interfaz gráfica en lugar de SQL puro, phpMyAdmin gestiona toda la reparación desde la pestaña Estructura.

1. Abre phpMyAdmin o Adminer y navega a la tabla wp_options.
2. Primero ocúpate de los IDs duplicados. Toma el valor más grande que exista en la columna option_id y renumera cada fila 0 una por una para que todos los valores sean únicos de nuevo. Este screencast muestra la renumeración:
3. Abre el editor de índices de la tabla:
4. Establece option_id como clave primaria:
5. Si ves el error Duplicate entry '0' for key 'PRIMARY', todavía quedan algunos IDs duplicados en la tabla:
6. Encuentra los duplicados restantes y aumenta sus valores para que ninguno se repita, luego añade la clave primaria de nuevo. Una vez que tenga éxito, vuelve a habilitar el autoincremento en option_id para que las filas futuras se numeren correctamente.

Corregir la clave primaria faltante con SQL

La misma reparación requiere tres sentencias si te sientes cómodo con la consola SQL. Ejecútalas en orden contra tu base de datos de WordPress.

Primero, da a cada fila 0 dañada un número único nuevo continuando a partir del option_id máximo actual:

SET @next := (SELECT MAX(option_id) FROM wp_options);
UPDATE wp_options
SET option_id = (@next := @next + 1)
WHERE option_id = 0;

A continuación, añade la clave primaria ahora que cada valor es único:

ALTER TABLE wp_options ADD PRIMARY KEY (option_id);

Por último, restaura el autoincremento para que WordPress vuelva a numerar las nuevas opciones automáticamente:

ALTER TABLE wp_options MODIFY option_id BIGINT(20) UNSIGNED NOT NULL AUTO_INCREMENT;

La sintaxis oficial de estas sentencias está documentada en el manual de MySQL bajo ALTER TABLE. Para la definición canónica de las columnas de wp_options, la descripción de la base de datos de WordPress lista los tipos de columna exactos que el núcleo de WordPress espera.

Verificar la corrección

Confirma que la reparación se mantuvo antes de confiar en la tabla:

SHOW CREATE TABLE wp_options;

La salida ahora debería incluir PRIMARY KEY (option_id) y mostrar AUTO_INCREMENT en la columna option_id. Como comprobación final, inserta y elimina una opción desechable, o simplemente guarda un ajuste en WordPress, y confirma que la nueva fila recibe un option_id único e incremental en lugar de otro 0.

Con la clave de nuevo en su sitio, puedes ejecutar la migración o la publicación de staging que antes fallaba. Aun así, haz una copia de seguridad nueva antes de la publicación para tener un punto de recuperación que incluya la tabla reparada.

Qué hacer si ALTER TABLE falla

El camino fácil cubre la mayoría de las instalaciones, pero algunos entornos necesitan un tratamiento adicional. Resuélvelos en orden:

• Duplicate entry '0' for key 'PRIMARY'. No todos los duplicados fueron renumerados. Vuelve a ejecutar la consulta de recuento de duplicados de la sección de diagnóstico, renumera las filas restantes y luego añade la clave de nuevo. Esta es, con diferencia, la razón más común por la que el paso ALTER TABLE se niega a ejecutarse.
• Tiempo de espera de bloqueo en una tabla grande. ALTER TABLE reescribe la tabla y mantiene un bloqueo mientras se ejecuta. En una tabla wp_options grande, o en un servidor de producción con mucho tráfico, la sentencia puede agotar el tiempo de espera. Ejecuta la reparación durante poco tráfico, en un clon de staging, o usa una herramienta de cambio de esquema en línea como pt-online-schema-change si tu hosting la proporciona.
• MyISAM en lugar de InnoDB. Los pasos funcionan en ambos motores, pero WordPress funciona mejor con InnoDB. Si SHOW CREATE TABLE wp_options informa ENGINE=MyISAM, considera convertirlo después de que la clave esté en su sitio con ALTER TABLE wp_options ENGINE=InnoDB. Haz una copia de seguridad primero, porque la conversión también reescribe la tabla.
• El hosting bloquea los cambios de esquema. Algunos hostings gestionados restringen las sentencias DDL directas o ejecutan la base de datos con un usuario sin privilegios ALTER. Si la sentencia falla con un error de permisos, pide a tu hosting que ejecute las tres sentencias por ti, o que conceda el privilegio temporalmente.

Un ALTER TABLE fallido es casi siempre uno de estos cuatro casos. Quien siga el error SQL subyacente en el registro del servidor puede encontrarlo expuesto también en la salida de depuración de WordPress; nuestra guía sobre cómo detectar un problema en las tablas de la base de datos de WordPress explica cómo activar ese registro.

Por qué esto importa para migraciones y publicaciones

La falta de una clave primaria es una de las razones más silenciosas por las que un traslado de sitio se atasca. Si una publicación de staging a producción agota el tiempo de espera o se aborta a mitad de la transferencia, la tabla wp_options es un sospechoso principal, especialmente cuando intervienen valores de opción serializados y el número de filas es grande. Lo mismo aplica cuando cambias de hosting: quienes lidian con siteurl y bucles de redirección después de un traslado, tema que cubrimos en nuestra guía sobre migrar siteurl en wp_options, son exactamente el público que también puede estar arrastrando una clave primaria dañada del servidor anterior. Corregir la clave primero elimina toda una categoría de fallos de migración antes de que empiecen.

Artículos relacionados

• La estructura de la base de datos de WordPress
• Publicar cambios de staging a producción
• Cómo migrar tu sitio de WordPress a un nuevo hosting
• Omitir pedidos y productos de WooCommerce
• Cómo encontrar el número de versión de WordPress de tu sitio web