Saltar al contenido principal

Problemas Comunes y Soluciones

Una guía completa de los problemas más comunes y sus soluciones.

Problemas de Instalación​

Página en Blanco Tras la Instalación​

Causa: Generalmente un problema con los permisos de archivos.

Solución:

# Revisar el registro de Laravel
tail -50 storage/logs/laravel.log

# Corregir permisos
sudo chmod -R 775 storage bootstrap/cache
sudo chown -R www-data:www-data storage bootstrap/cache

Errores "Class Not Found"​

Causa: Las dependencias de Composer no están instaladas o el autoloader no fue generado.

Solución:

composer install --no-dev --optimize-autoloader
php artisan config:clear

El Instalador Muestra "Already Installed"​

Causa: El archivo storage/installed.lock existe.

Solución: Si necesitas volver a ejecutar el instalador:

rm storage/installed.lock

Luego visita /install de nuevo.

CSS/JS No Carga (Página Sin Estilo)​

Causa: Enlace simbólico de almacenamiento faltante o problema con la ruta de recursos.

Solución:

php artisan storage:link
php artisan config:clear
php artisan view:clear

También verifica que tu APP_URL en .env coincida con tu dominio real (incluyendo https://).

Problemas de Base de Datos​

"SQLSTATE[HY000] [2002] Connection Refused"​

Causa: MySQL no está funcionando o el host es incorrecto.

Solución:

  • Comprueba que MySQL esté funcionando: sudo systemctl status mysql
  • Prueba con 127.0.0.1 en lugar de localhost en .env
  • Verifica el puerto (predeterminado: 3306)

"SQLSTATE[HY000] [1045] Access Denied"​

Causa: Credenciales de base de datos incorrectas.

Solución:

  • Verifica el usuario/contraseña en .env
  • Prueba la conexión: mysql -u your_user -p your_database
  • Vuelve a otorgar permisos:
GRANT ALL PRIVILEGES ON feedbackpulse.* TO 'your_user'@'localhost';
FLUSH PRIVILEGES;

Los Emojis Se Muestran como ????​

Causa: El conjunto de caracteres de la base de datos es utf8 en lugar de utf8mb4.

Solución:

ALTER DATABASE feedbackpulse CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

Problemas del Servidor Web​

Todas las Rutas Devuelven 404​

Solución para Apache:

sudo a2enmod rewrite
sudo systemctl restart apache2

Asegúrate de que AllowOverride All esté configurado en tu host virtual.

Solución para Nginx: Asegúrate de que tu bloque de servidor tenga:

location / {
    try_files $uri $uri/ /index.php?$query_string;
}

502 Bad Gateway (Nginx)​

Causa: PHP-FPM no está funcionando o la ruta del socket es incorrecta.

Solución:

sudo systemctl restart php8.4-fpm
# Comprobar la ruta del socket
ls /var/run/php/php8.4-fpm.sock

413 Request Entity Too Large​

Causa: Límite de tamaño de subida demasiado bajo.

Solución (Nginx):

client_max_body_size 20M;

Solución (PHP):

upload_max_filesize = 20M
post_max_size = 25M

Problemas de Autenticación​

"CSRF Token Mismatch" (Error 419)​

Causa: Sesión expirada o problema con las cookies.

Solución:

  • Limpia las cookies del navegador e inténtalo de nuevo
  • Comprueba SESSION_DOMAIN en .env (establécelo en .yourdomain.com para subdominios)
  • Asegúrate de que SESSION_SECURE_COOKIE=true solo si usas HTTPS

No Se Puede Iniciar Sesión Tras Restablecer la Contraseña​

Causa: El navegador guardó en caché la sesión antigua.

Solución: Limpia las cookies del navegador o usa el modo incógnito.

El Inicio de Sesión Social Devuelve un Error​

Causa: Desajuste en la URL de devolución de llamada.

Solución: Asegúrate de que la URL de devolución de llamada en la consola de Google/GitHub coincida exactamente con:

  • Google: https://yourdomain.com/auth/google/callback
  • GitHub: https://yourdomain.com/auth/github/callback

Problemas de Pago​

Consulta Problemas con Pasarelas de Pago para la solución detallada de problemas de pago.

Problemas de Correo Electrónico​

Consulta Correo No Se Envía para la solución detallada de problemas de correo electrónico.

Problemas de Rendimiento​

Consulta Optimización de Rendimiento para consejos de optimización.

Problemas de Caché​

Ante la duda, limpia todos los cachés:

php artisan optimize:clear

Esto limpia:

  • Caché de configuración
  • Caché de rutas
  • Caché de vistas
  • Caché de la aplicación
  • Caché de clases compiladas

Modo de Depuración (Temporal)​

Para ver mensajes de error detallados:

  1. Edita .env:
APP_DEBUG=true
LOG_LEVEL=debug
  1. Reproduce el error
  2. Comprueba la página de error o storage/logs/laravel.log
  3. ¡Inmediatamente establece APP_DEBUG=false cuando termines!
aviso

Nunca dejes APP_DEBUG=true en producción. Expone información sensible.

Obtener Ayuda​

Si ninguna de las soluciones anteriores resuelve tu problema:

  1. Comprueba storage/logs/laravel.log para la traza completa del error
  2. Comprueba el registro de errores de tu servidor web (/var/log/nginx/error.log o /var/log/apache2/error.log)
  3. Busca en los comentarios del artículo de CodeCanyon problemas similares
  4. Abre un ticket de soporte con:
    • Mensaje de error (del registro)
    • Versión de PHP (php -v)
    • Versión de Laravel
    • Detalles del servidor (SO, servidor web, versión de MySQL)
    • Pasos para reproducir el error