¿Por qué fallaba el Buscador Inteligente de Joomla 5 y cómo solucionarlo?

Introducción

Hace unas semanas nos encontramos con un problema bastante molesto en un sitio Joomla 5. Al intentar indexar el Buscador Inteligente (Smart Search), aparecía el siguiente mensaje de error:

Se ha producido un error
Duplicate entry 'dirección-*' for key 'idx_term_language'

El indexador se detenía inmediatamente, sin importar cuántos artículos teníamos ni qué plugins estaban activos. Este fallo impedía que la búsqueda inteligente funcionara, lo que afecta directamente a la experiencia de los usuarios al buscar contenido en el sitio.

En esta entrada quiero contaros cómo detectamos el error, qué pruebas realizamos y la solución que finalmente funcionó, paso a paso, para que podáis aplicarla vosotros si os encontráis en la misma situación.

Cómo detectamos el error

Lo primero que hicimos fue mirar la tabla donde se almacenan los términos indexados por Smart Search: finder_terms. Ejecutamos un simple SELECT COUNT(*) para ver si había algún registro previo que pudiera causar el duplicado:

SELECT COUNT(*) FROM finder_terms;

El resultado fue 0 registros. Esto nos confirmó que el error no se debía a datos existentes, sino que Joomla estaba generando el mismo término dos veces en memoria durante el proceso de indexación.

A continuación, revisamos el índice que bloqueaba la inserción:

SHOW INDEX FROM finder_terms WHERE Key_name='idx_term_language';

Todo estaba correcto: era un índice UNIQUE sobre las columnas (term, language). Por tanto, la base de datos estaba funcionando bien, y el problema estaba en la lógica de Joomla, no en la tabla ni en el índice.

¿A qué se debe este problema?

Tras investigar, descubrimos que el error ocurre principalmente por tres motivos:

1. Normalización Unicode en PHP: Joomla genera los términos internamente y normaliza los caracteres especiales. Por ejemplo, dirección se convierte en dos versiones que para PHP parecen distintas pero MySQL las considera iguales.

2. Collation de la base de datos: con la configuración por defecto (utf8mb4_unicode_ci), MySQL no distingue correctamente ciertos acentos, lo que provoca que detecte duplicados.

3. Idioma global (*): Joomla asigna el mismo término a todos los idiomas, aumentando la probabilidad de que se produzca un conflicto.

En pocas palabras, el duplicado no estaba en la base de datos, sino que se generaba durante la creación de términos en memoria, justo antes de insertarlos.

Solución paso a paso

Después de analizar el problema, aplicamos la siguiente solución:

1. Vaciar la tabla de términos:

TRUNCATE TABLE finder_terms;

Esto eliminó cualquier posible registro residual y nos dio un punto de partida limpio.

1. Cambiar la collation de la columna term a binaria:

ALTER TABLE finder_terms 
MODIFY COLUMN term VARCHAR(255) CHARACTER SET utf8mb4 COLLATE utf8mb4_bin NOT NULL;

¿Por qué esto funciona?

• utf8mb4_bin distingue mayúsculas, minúsculas y acentos.
• Evita que MySQL considere duplicados términos que solo se diferencian por un acento.

• Permite que Joomla inserte todos los términos, incluso con caracteres especiales o multilenguaje, sin que el índice UNIQUE bloquee la operación.

• Reindexar desde Joomla:

  • Backend → Smart Search → Clear Index
  • Backend → Smart Search → Index

El proceso se completó sin errores, y ahora todos los términos se insertan correctamente, incluyendo “dirección” y otros con acentos.

Medidas preventivas

Para que este error no vuelva a aparecer:

• Hacer siempre un backup completo antes de modificar tablas o collation.
• Revisar los plugins de campos personalizados o SEO, ya que pueden generar tokens duplicados.
• Evitar duplicar contenido con caracteres especiales en idioma global.
• Comprobar periódicamente que Smart Search puede indexar sin problemas tras cambios importantes en el sitio.

Conclusión

El error Duplicate entry 'dirección-*' for key 'idx_term_language' en Joomla 5 es un caso típico de colisión de términos generados internamente, causado por la normalización Unicode y la collation de la base de datos.

Vaciar la tabla de términos y aplicar collation binaria a la columna term es la forma más efectiva de solucionarlo. Tras aplicar estos pasos, el Buscador Inteligente funciona correctamente, incluso con contenido multilenguaje y caracteres especiales.

Si alguna vez os encontráis con un error similar, ahora sabéis cómo identificarlo y solucionarlo paso a paso, sin afectar la integridad de vuestro sitio.