Error de conexión a BD en PrestaShop cPanel: Solución fácil

Este es un escenario que, como técnico de soporte, vemos con frecuencia. Te conectas a tu tienda PrestaShop y, en lugar de ver tus productos, te encuentras con un mensaje frustrante: "Error de conexión a la base de datos" o el famoso "PrestaShop cannot connect to database". No te preocupes, es uno de los problemas más comunes y, en la mayoría de los casos, tiene una solución sencilla.

En esta guía extensa y detallada, te explicaré paso a paso cómo solucionar el error BD PrestaShop cPanel, desde lo más básico hasta lo más técnico. Soy tu técnico de soporte amigable, y vamos a resolverlo juntos.

[INFO] Este artículo está diseñado para usuarios de cPanel, el panel de control de hosting más popular. Si usas Syspanel (antes conocido como HestiaCP, puerto 2106), los conceptos son los mismos, pero la interfaz varía ligeramente.

¿Qué significa exactamente el error "PrestaShop cannot connect to database"?

Cuando ves este mensaje, significa que PrestaShop intentó comunicarse con el motor de base de datos (MySQL o MariaDB) pero no pudo establecer la conexión. Las causas más comunes son:

Credenciales incorrectas: El usuario, la contraseña o el nombre de la base de datos en tu archivo app/config/parameters.php no coinciden con los reales.
Servidor de base de datos caído o sobrecargado: Tu hosting puede tener un problema temporal.
Usuario sin permisos: El usuario de la base de datos no tiene acceso a la base de datos especificada.
Archivo de configuración corrupto o mal editado.
Problemas con el prefijo de las tablas (menos común, pero posible).
Firewall o restricciones de IP (raro en entornos compartidos).

Vamos a atacar cada una de estas causas en orden.

Paso 1: Verificar el estado del servidor de base de datos (Lo más rápido)

Antes de tocar archivos o configuraciones, asegúrate de que el problema no sea de tu proveedor de hosting.

Accede a tu cPanel (normalmente tudominio.com/cpanel o tudominio.com:2083).
Busca la sección "Base de Datos" y haz clic en "phpMyAdmin".
Si phpMyAdmin se abre correctamente y ves tus bases de datos, el servidor MySQL está funcionando. Si no se abre o ves un error, el problema es del hosting. Contacta a tu soporte técnico y diles: "Tengo un error de conexión a la base de datos en PrestaShop, no puedo acceder a phpMyAdmin".
Si phpMyAdmin funciona, el servidor está bien. Pasemos al siguiente paso.

[TIP] Si usas Syspanel (puerto 2106), el acceso a phpMyAdmin suele estar en la sección "Bases de Datos" o "Servicios".

Paso 2: Localizar y revisar el archivo de configuración `parameters.php`

Este es el archivo que contiene las credenciales que PrestaShop usa para conectarse. Es el punto más común de error.

¿Cómo encontrar el archivo?

Desde tu cPanel, ve a la sección "Archivos" y haz clic en "Administrador de Archivos".
Selecciona la raíz de tu sitio web (normalmente public_html o www).
Navega a la carpeta: public_html/app/config/.
Busca el archivo parameters.php.
Haz clic derecho sobre él y selecciona "Editar" (o "Code Editor").

¿Qué buscar dentro del archivo?

Dentro del archivo verás un código PHP con información de la base de datos. Busca específicamente estas líneas:

'database_host' => 'localhost',
'database_port' => '',
'database_name' => 'tu_usuario_cpanel_nombre_bd',
'database_user' => 'tu_usuario_cpanel_usuario_bd',
'database_password' => 'tu_contraseña_bd',

Verifica cada uno de estos datos:

database_host: Casi siempre es localhost en hosting compartido. Si tu hosting te dio un host específico (ej: mysql.tudominio.com), pónlo aquí.
database_name: Este nombre suele tener el formato usuario_cpanel_nombre_bd. Debe coincidir exactamente con el nombre de la base de datos que ves en tu cPanel en la sección "Bases de Datos MySQL".
database_user: Similar al nombre, suele ser usuario_cpanel_usuario_bd. Debe coincidir exactamente con el nombre de usuario de la base de datos.
database_password: La contraseña que asignaste a ese usuario. Asegúrate de que no tenga espacios al principio o al final.

[WARNING] ¡Cuidado! No copies y pegues contraseñas desde Word o Google Docs, ya que pueden agregar caracteres invisibles. Es mejor escribirla manualmente o copiarla desde el cPanel.

¿Cómo obtener las credenciales correctas desde cPanel?

En tu cPanel, ve a "Bases de Datos MySQL".
Verás una lista de bases de datos y usuarios asociados.
Verifica que el usuario esté añadido a la base de datos (debe aparecer un check o un enlace "Añadir usuario a la base de datos"). Si no, añádelo.
Si tienes dudas, crea un nuevo usuario y contraseña, asígnale todos los privilegios a la base de datos, y luego actualiza el archivo parameters.php con esos nuevos datos.

Ejemplo de cómo debe verse en cPanel:

Base de datos: midominio_presta
Usuario: midominio_admin
Contraseña: MiClaveSegura2024!

En parameters.php:

'database_name' => 'midominio_presta',
'database_user' => 'midominio_admin',
'database_password' => 'MiClaveSegura2024!',

Paso 3: Verificar los permisos del usuario (El olvido más común)

A veces el usuario existe y la contraseña es correcta, pero no tiene permisos sobre la base de datos. Es como tener la llave de un coche, pero no tener permiso para conducirlo.

En cPanel, ve a "Bases de Datos MySQL".
En la sección "Usuarios en bases de datos", busca tu base de datos y tu usuario.
Si ves el mensaje "Usuario no añadido a la base de datos", selecciona el usuario y la base de datos y haz clic en "Añadir".
En la siguiente pantalla, marca la casilla "TODOS LOS PRIVILEGIOS" y luego haz clic en "Realizar cambios".

[TIP] Si ya estaba añadido, a veces es buena práctica eliminar al usuario de la base de datos y volver a añadirlo con todos los privilegios. Esto refresca la conexión.

Paso 4: Comprobar el archivo `settings.inc.php` (Versiones antiguas de PrestaShop)

Si tu PrestaShop es anterior a la versión 1.7, la configuración no está en parameters.php, sino en un archivo llamado settings.inc.php.

La ruta es: /config/settings.inc.php (en la raíz de tu instalación).
Las variables son similares: _DB_SERVER_, _DB_NAME_, _DB_USER_, _DB_PASSWD_.
El proceso de verificación es exactamente el mismo que el del Paso 2. Edítalo con cuidado.

[INFO] Para PrestaShop 1.7 y 8.x, solo existe parameters.php. Si tienes una versión muy antigua (1.6 o anterior), busca settings.inc.php.

Paso 5: Probar la conexión manualmente con un script (Solución avanzada)

Si después de verificar todo sigues con el error, podemos crear un script PHP simple para probar la conexión directamente. Esto nos dirá si el problema es de PrestaShop o de la base de datos en sí.

Desde el Administrador de Archivos de cPanel, navega a la raíz de tu sitio (public_html).
Crea un nuevo archivo llamado test_db.php.
Pega el siguiente código, reemplazando los datos con los tuyos:

<?php
$host = 'localhost'; // O el host que tengas
$user = 'tu_usuario_cpanel_usuario_bd'; // Tu usuario de BD
$pass = 'tu_contraseña_bd'; // Tu contraseña
$db   = 'tu_usuario_cpanel_nombre_bd'; // Tu nombre de BD

$conn = new mysqli($host, $user, $pass, $db);

if ($conn->connect_error) {
    die("Error de conexión: " . $conn->connect_error);
} else {
    echo "Conexión exitosa a la base de datos.";
}

$conn->close();
?>

Guarda el archivo.
Abre en tu navegador: tudominio.com/test_db.php.
Si ves "Conexión exitosa": El problema es exclusivamente de la configuración de PrestaShop (archivo parameters.php mal escrito, permisos de archivo, etc.). Revisa el Paso 2 al pie de la letra.
Si ves "Error de conexión": El problema es de la base de datos. Vuelve al Paso 1 y 3. Si todo parece correcto, contacta a tu hosting.

[WARNING] ¡IMPORTANTE! Después de la prueba, ELIMINA el archivo test_db.php de tu servidor. Dejarlo expuesto es un grave riesgo de seguridad, ya que muestra información de tu base de datos.

Paso 6: Restaurar una copia de seguridad de `parameters.php`

Si estás seguro de que los datos son correctos pero el error persiste, es posible que el archivo parameters.php esté corrupto o tenga un error de sintaxis.

Si tienes una copia de seguridad de tu sitio, localiza el parameters.php original.
Reemplaza el archivo actual por el de la copia de seguridad.
Si no tienes copia, puedes descargar una copia limpia de PrestaShop desde la página oficial (misma versión que la tuya), extraer el archivo parameters.php de la carpeta app/config/ y luego sustituir solo las líneas de la base de datos con tus credenciales. No reemplaces todo el archivo, solo las líneas de conexión.

[TIP] Siempre, siempre guarda una copia de seguridad de tu archivo parameters.php antes de editarlo. Puedes descargarlo a tu PC.

Preguntas Frecuentes (FAQ)

1. ¿Qué hago si veo "PrestaShop cannot connect to database" después de migrar mi web?

Este es el escenario más común. La causa es que las credenciales en parameters.php siguen siendo las del hosting antiguo. Ve directo al Paso 2 y actualiza los datos con los de tu nuevo hosting.

2. ¿Por qué mi contraseña de base de datos no funciona si la copié de cPanel?

A veces cPanel muestra la contraseña enmascarada o con un enlace para "mostrar". Asegúrate de copiar el texto exacto. Si tienes dudas, genera una nueva contraseña desde cPanel (en "Bases de Datos MySQL") y actualízala en parameters.php.

3. ¿El error puede deberse a un plugin o tema?

No directamente. El error de conexión a la base de datos es un problema de infraestructura, no de código. Sin embargo, un módulo o tema mal programado podría haber modificado el archivo parameters.php. Si el error apareció después de instalar algo, revisa si ese módulo alteró el archivo de configuración.

4. Uso Syspanel (HestiaCP, puerto 2106), ¿es diferente?

Los pasos son los mismos. La diferencia está en la interfaz. En Syspanel:

El acceso a archivos suele ser por "Administrador de Archivos" en el menú principal.
Las bases de datos están en "Bases de Datos".
El host de la base de datos suele ser localhost también.
El puerto de acceso a Syspanel es el 2106.

5. ¿Qué significa "Error de conexión: Too many connections"?

Esto significa que tu base de datos ha alcanzado el límite de conexiones simultáneas permitidas por tu plan de hosting. Contacta a tu proveedor para aumentar el límite o revisa si tienes algún proceso (como un cron) que esté abriendo muchas conexiones sin cerrarlas.

6. Después de solucionar el error, mi tienda se ve en blanco o con errores. ¿Qué hago?

Esto suele pasar si el archivo parameters.php se editó mal (por ejemplo, se borró una coma o una comilla). Revisa el archivo con un editor de código que resalte la sintaxis PHP. Busca errores como:

Faltan comillas al final de una línea.
Faltan comas al final de una línea (excepto la última).
Puntos y coma mal colocados.

Si no encuentras el error, restaura el archivo desde tu copia de seguridad y vuelve a intentarlo.

Conclusión y resumen

El error de conexión a la base de datos en PrestaShop es frustrante pero, como has visto, se soluciona siguiendo un orden lógico:

Verifica que el servidor MySQL funcione (phpMyAdmin).
Revisa y corrige el archivo parameters.php (o settings.inc.php).
Asegúrate de que el usuario tenga todos los privilegios sobre la base de datos.
Prueba la conexión con un script para aislar el problema.
Si nada funciona, contacta a tu hosting (puede ser un problema del servidor).

[INFO] Recuerda: la paciencia es clave. No edites archivos sin hacer una copia de seguridad primero. Y si te sientes abrumado, siempre puedes pedir ayuda a tu soporte técnico o a un profesional.

Espero que esta guía te haya sido de gran ayuda. ¡Tu tienda PrestaShop volverá a estar online en poco tiempo!