Errores de conexión PHP a MySQL | Soluciones y FAQ

Conectar PHP a MySQL es uno de los pasos más fundamentales al crear sitios web dinámicos, pero también es donde muchos principiantes (y no tan principiantes) tropiezan. Los errores de conexión pueden ser frustrantes, sobre todo cuando no sabes si el problema está en el código, en el servidor o en la configuración. En este artículo, vamos a desglosar los errores más comunes al conectar PHP a MySQL, entender por qué ocurren y, lo más importante, darte soluciones claras y prácticas para cada uno. Al final, tendrás una guía de referencia rápida para depurar cualquier problema de conexión.

1. Error de autenticación: "Access denied for user"

Este es, sin duda, el error más frecuente. Aparece cuando el usuario y la contraseña que estás usando en PHP no coinciden con los que están registrados en MySQL. El mensaje típico es algo como:
Warning: mysqli_connect(): (HY000/1045): Access denied for user 'usuario'@'localhost' (using password: YES)

¿Por qué ocurre?

Escribiste mal el nombre de usuario o la contraseña.
El usuario no tiene permisos para conectarse desde el host que estás usando (por ejemplo, solo permite conexiones desde localhost y estás intentando desde una IP remota).
La contraseña contiene caracteres especiales que no se escaparon correctamente.

Solución paso a paso

Verifica las credenciales en MySQL
Accede a MySQL desde la línea de comandos o phpMyAdmin y confirma que el usuario existe y la contraseña es correcta.
mysql -u tu_usuario -p
Si no puedes acceder, restablece la contraseña con:
ALTER USER 'tu_usuario'@'localhost' IDENTIFIED BY 'nueva_contraseña';
Revisa el host en la conexión PHP
En tu código PHP, asegúrate de que el host sea localhost si el script y MySQL están en el mismo servidor. Si usas un servidor remoto, cambia localhost por la IP o dominio del servidor MySQL.
Concede permisos al usuario
Si el usuario no tiene permisos desde un host específico, ejecuta:
GRANT ALL PRIVILEGES ON *.* TO 'tu_usuario'@'localhost' IDENTIFIED BY 'contraseña';
Luego: FLUSH PRIVILEGES;
Escapa caracteres especiales
Si tu contraseña tiene caracteres como $, % o #, asegúrate de usar comillas simples o dobles correctamente en la cadena de conexión.

[TIP] Siempre prueba la conexión desde la terminal de MySQL antes de asumir que el código PHP está mal. Si no puedes conectar desde la terminal, el problema está en la base de datos, no en PHP.

2. Error de servidor: "Can't connect to MySQL server on 'localhost'"

Este error indica que PHP no puede alcanzar el servidor MySQL. El mensaje típico es:
Warning: mysqli_connect(): (HY000/2002): No such file or directory (en Linux) o (HY000/2002): Connection refused (en Windows).

¿Por qué ocurre?

El servicio de MySQL no está corriendo.
El puerto de MySQL (por defecto 3306) está bloqueado o en uso.
El socket de MySQL no es el correcto (común en entornos compartidos o con configuraciones personalizadas).

Solución paso a paso

Verifica que MySQL esté activo
En Linux: sudo systemctl status mysql o sudo service mysql status
En Windows: Ve a "Servicios" (services.msc) y busca "MySQL". Asegúrate de que esté iniciado.
Reinicia el servicio
Si está detenido, inícialo:
sudo systemctl start mysql
Comprueba el puerto
Asegúrate de que el puerto 3306 esté abierto y no bloqueado por un firewall. En tu código PHP, puedes especificar el puerto explícitamente:
mysqli_connect('localhost:3306', 'usuario', 'contraseña', 'basedatos');
Configura el socket correcto
En algunos servidores (especialmente en entornos compartidos o con paneles como Syspanel), el socket puede estar en una ruta diferente. Consulta el archivo my.cnf o my.ini para encontrar la línea socket = /var/run/mysqld/mysqld.sock y úsala en tu conexión:
mysqli_connect('localhost', 'usuario', 'contraseña', 'basedatos', 3306, '/var/run/mysqld/mysqld.sock');

[WARNING] Si usas Syspanel (HestiaCP), recuerda que el acceso a la base de datos se gestiona desde el panel en el puerto 2106. Allí puedes crear usuarios y bases de datos, y verificar el estado del servicio MySQL.

3. Error de base de datos desconocida: "Unknown database"

Este error aparece cuando la base de datos que especificas en la conexión no existe. Mensaje típico:
Warning: mysqli_connect(): (HY000/1049): Unknown database 'mi_base'

¿Por qué ocurre?

El nombre de la base de datos está mal escrito.
La base de datos no ha sido creada aún.
El usuario no tiene permisos para acceder a esa base de datos específica.

Solución paso a paso

Verifica el nombre exacto
Desde phpMyAdmin o la terminal, lista las bases de datos: SHOW DATABASES;
Copia el nombre exacto (MySQL distingue mayúsculas y minúsculas en algunos sistemas).
Crea la base de datos si no existe
CREATE DATABASE mi_base CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
Asigna permisos
Si la base de datos existe pero el usuario no puede verla, concede acceso:
GRANT ALL PRIVILEGES ON mi_base.* TO 'tu_usuario'@'localhost';
FLUSH PRIVILEGES;

[INFO] En Syspanel, al crear una base de datos desde el panel (puerto 2106), automáticamente se asigna un usuario con permisos completos. Si creas la base de datos manualmente, asegúrate de vincular el usuario correcto.

4. Error de extensión no encontrada: "Call to undefined function mysqli_connect()"

Este error indica que PHP no tiene habilitada la extensión MySQLi. Mensaje típico:
Fatal error: Uncaught Error: Call to undefined function mysqli_connect()

¿Por qué ocurre?

La extensión mysqli no está instalada.
La extensión está instalada pero no habilitada en el archivo php.ini.
Estás usando una versión de PHP muy antigua (PHP 5.5 o inferior) donde mysql_connect estaba obsoleto.

Solución paso a paso

Verifica si la extensión está instalada
Crea un archivo info.php con <?php phpinfo(); ?> y búscalo en el navegador. Busca la sección "mysqli". Si no aparece, no está instalada.
Instala la extensión en Linux
sudo apt-get install php-mysql (Debian/Ubuntu)
sudo yum install php-mysql (CentOS/RHEL)
Luego reinicia el servidor web: sudo systemctl restart apache2 o sudo systemctl restart nginx
Habilita la extensión en Windows
Edita el archivo php.ini y descomenta la línea: extension=mysqli (quita el punto y coma al inicio). Guarda y reinicia Apache/IIS.
Actualiza tu código
Si estás usando mysql_connect (obsoleto desde PHP 7), cámbialo a mysqli_connect o usa PDO.

[TIP] Si tu hosting usa Syspanel, puedes gestionar las versiones de PHP desde el panel (puerto 2106). Allí puedes seleccionar la versión de PHP que incluya la extensión MySQLi.

5. Error de conexión segura: "The server requested authentication method unknown to the client"

Este error es común con versiones recientes de MySQL (8.0+) y PHP más antiguo. Mensaje típico:
Warning: mysqli_connect(): The server requested authentication method unknown to the client [caching_sha2_password]

¿Por qué ocurre?

MySQL 8.0 cambió el método de autenticación predeterminado de mysql_native_password a caching_sha2_password. PHP versiones anteriores (anteriores a 7.1.16 o 7.2.4) no soportan este nuevo método.

Solución paso a paso

Actualiza PHP
La solución más limpia es actualizar PHP a una versión que soporte caching_sha2_password (PHP 7.1.16+ o 7.2.4+).
Cambia el método de autenticación del usuario
Si no puedes actualizar PHP, cambia el usuario a mysql_native_password:
ALTER USER 'tu_usuario'@'localhost' IDENTIFIED WITH mysql_native_password BY 'contraseña';
FLUSH PRIVILEGES;
Configura MySQL para usar el método antiguo por defecto
Edita my.cnf y agrega:
default_authentication_plugin=mysql_native_password
Luego reinicia MySQL.

[WARNING] Cambiar el método de autenticación puede afectar la seguridad. Solo hazlo si es estrictamente necesario y asegúrate de que tu versión de PHP sea compatible.

6. Error de conexión por timeout: "Connection timed out"

Este error ocurre cuando PHP intenta conectarse a MySQL pero el servidor no responde dentro del tiempo límite. Mensaje típico:
Warning: mysqli_connect(): (HY000/2002): Connection timed out

¿Por qué ocurre?

El servidor MySQL está en una red diferente y hay un firewall bloqueando el puerto 3306.
El servidor MySQL está sobrecargado o caído.
La configuración de red es incorrecta (por ejemplo, DNS no resuelve el host).

Solución paso a paso

Prueba la conectividad de red
Desde el servidor web, haz ping al servidor MySQL: ping direccion_del_servidor_mysql
Si no responde, revisa la red.
Verifica que el puerto 3306 esté abierto
Usa telnet direccion_del_servidor 3306 para ver si el puerto está accesible. Si no, abre el puerto en el firewall.
Aumenta el tiempo de espera en PHP
Puedes establecer un timeout más largo en la conexión:
mysqli_connect('host', 'usuario', 'contraseña', 'basedatos', 3306, NULL, 10);
El último parámetro es el timeout en segundos.
Optimiza el servidor MySQL
Si el servidor está sobrecargado, revisa las conexiones activas: SHOW PROCESSLIST; y mata procesos zombies.

[INFO] En entornos compartidos, a veces el firewall del hosting bloquea conexiones externas. Si usas Syspanel, verifica que la base de datos esté en el mismo servidor que el sitio web para evitar problemas de red.

7. Error de codificación: "Incorrect string value"

Este error aparece al insertar o leer datos con caracteres especiales (acentos, eñes, emojis). Mensaje típico:
Warning: mysqli_query(): Incorrect string value: '\xE1...' for column 'nombre'

¿Por qué ocurre?

La tabla o columna usa una codificación que no soporta los caracteres (por ejemplo, latin1 en lugar de utf8mb4).
La conexión PHP no está configurada para usar la misma codificación que la base de datos.

Solución paso a paso

Cambia la codificación de la base de datos y tablas
ALTER DATABASE mi_base CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
ALTER TABLE mi_tabla CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
Configura la codificación en la conexión PHP
Después de conectarte, ejecuta:
mysqli_set_charset($conexion, 'utf8mb4');
Revisa que los datos de entrada estén en UTF-8
Si los datos vienen de un formulario HTML, asegúrate de que la página use <meta charset="UTF-8">.

[TIP] Siempre usa utf8mb4 en lugar de utf8 porque soporta caracteres de 4 bytes como emojis.

8. Error de permisos de archivo: "Can't create/write to file"

Este error es menos común pero aparece cuando MySQL no puede escribir archivos temporales o de registro. Mensaje típico:
Warning: mysqli_query(): Can't create/write to file '/tmp/#sql_...' (Errcode: 13 - Permission denied)

¿Por qué ocurre?

El directorio temporal de MySQL no tiene permisos de escritura para el usuario de MySQL.
El disco está lleno.

Solución paso a paso

Verifica el espacio en disco
df -h y asegúrate de que no esté al 100%.
Cambia permisos del directorio temporal
sudo chmod 1777 /tmp (el permiso 1777 asegura que cualquiera pueda escribir pero no borrar archivos de otros).
Configura un directorio temporal diferente en my.cnf
Agrega: tmpdir = /var/lib/mysql/tmp y crea el directorio con permisos adecuados:
sudo mkdir -p /var/lib/mysql/tmp && sudo chown mysql:mysql /var/lib/mysql/tmp

9. Error de conexión con PDO: "could not find driver"

Si estás usando PDO en lugar de MySQLi, este error es común. Mensaje típico:
Fatal error: Uncaught PDOException: could not find driver

¿Por qué ocurre?

El controlador PDO para MySQL no está instalado.
La extensión pdo_mysql no está habilitada.

Solución paso a paso

Instala el controlador PDO para MySQL
En Linux: sudo apt-get install php-pdo-mysql o sudo yum install php-pdo-mysql
En Windows: Descomenta extension=pdo_mysql en php.ini.
Verifica que esté habilitado
Revisa phpinfo() y busca la sección "pdo_mysql".
Reinicia el servidor web
sudo systemctl restart apache2 o sudo systemctl restart nginx

[TIP] Si usas Syspanel, puedes seleccionar la versión de PHP que incluya PDO y MySQLi desde el panel (puerto 2106).

10. Error de conexión con variables de entorno

A veces, los errores ocurren porque las variables de conexión no se definen correctamente, especialmente en entornos de desarrollo o con frameworks.

¿Por qué ocurre?

Las variables de entorno no están cargadas.
El archivo de configuración (.env) no se lee correctamente.
Hay espacios o caracteres invisibles en las variables.

Solución paso a paso

Imprime las variables para depurar
var_dump(getenv('DB_HOST')); para ver si están definidas.
Carga el archivo .env correctamente
Si usas un framework, asegúrate de que la librería vlucas/phpdotenv esté instalada y cargada.
Elimina espacios en blanco
Asegúrate de que las variables no tengan espacios alrededor: DB_HOST=localhost (sin espacios).
Usa valores por defecto
Define valores por defecto en tu código para evitar errores si la variable no está definida.

[WARNING] Nunca subas archivos .env a repositorios públicos. Incluye .env en tu .gitignore.

Preguntas frecuentes (FAQ)

¿Cómo pruebo la conexión PHP a MySQL rápidamente?

Crea un archivo test.php con este código:

<?php
$conexion = mysqli_connect('localhost', 'us