🎯 Troubleshooting

Esta sección tiene como objetivo ayudar a identificar y resolver los errores más comunes que pueden presentarse durante la integración de **FusionAuth** con proyectos Laravel mediante el módulo de autenticación y Socialite Provider.

Antes de revisar errores específicos, se recomienda validar que se hayan completado correctamente los siguientes puntos:

1. Instalación de dependencias mediante Composer.
2. Configuración de config/services.php.
3. Configuración de variables de entorno en .env.
4. Registro del provider de Socialite.
5. Configuración del modelo User.
6. Modificación de la tabla users.
7. Coincidencia exacta de la URI de callback entre Laravel y FusionAuth.

No redirige al login de FusionAuth

Problema

Al ingresar a la ruta: http://${base_url}/autenticacion/login

la aplicación no redirige al formulario de inicio de sesión de FusionAuth, muestra una pantalla en blanco, error 404 o permanece en la misma página.

Posibles causas

• El módulo de autenticación no está instalado correctamente.
• Las rutas del módulo no fueron registradas.
• El proyecto no reconoce el módulo de autenticación.
• La URL base del proyecto no corresponde con la URL utilizada en el navegador.
• El caché de rutas o configuración de Laravel está desactualizado.

Solución recomendada

Ejecutar los siguientes comandos dentro del proyecto Laravel:

php artisan optimize:clear
php artisan route:clear
php artisan config:clear
php artisan cache:clear
composer dump-autoload

Después, validar que la ruta exista ejecutando:

php artisan route:list | grep autenticacion

Se debe verificar que existan rutas relacionadas con:

/autenticacion/login
/autenticacion/callback

Si las rutas no aparecen, revisar que el módulo de autenticación se encuentre instalado correctamente dentro de la estructura de módulos del proyecto.

---

Error por URI de callback incorrecta

Problema

FusionAuth muestra un error relacionado con la URL de redirección o callback.

Puede presentarse como:

Invalid redirect_uri

o

The redirect_uri is not valid

Posibles causas

• La variable FUSIONAUTH_REDIRECT_URI no coincide exactamente con la configurada en FusionAuth.
• Se está usando http en lugar de https, o viceversa.
• La aplicación tiene un prefijo en la URL y no fue considerado.
• La variable APP_URL está mal configurada.
• Hay una diagonal / extra o faltante en la URL.

Solución recomendada

Validar en el archivo .env:

APP_URL=https://dominio-del-proyecto.gob.mx
FUSIONAUTH_REDIRECT_URI=${APP_URL}/autenticacion/callback

La URI generada debe coincidir exactamente con la configurada en FusionAuth.

Ejemplo:

https://dominio-del-proyecto.gob.mx/autenticacion/callback

También se recomienda limpiar caché de configuración:

php artisan config:clear
php artisan optimize:clear

Importante: la URI de callback debe coincidir exactamente. Para FusionAuth, http://sistema.gob.mx/callback y https://sistema.gob.mx/callback son rutas diferentes.

---

Error 500 después del callback

Problema

El usuario inicia sesión en FusionAuth, pero al regresar a Laravel se muestra un error 500.

Posibles causas

• Faltan columnas en la tabla users.
• El modelo User no tiene los campos agregados en $fillable.
• Los campos data o registration_data no tienen casting como array.
• La base de datos no acepta valores nulos en campos requeridos.
• El campo password no permite valores nulos.
• Error al guardar los tokens de FusionAuth.
• Solución recomendada

Validar que la tabla users tenga los siguientes campos:

fusionauth_id
fusionauth_access_token
fusionauth_refresh_token
profile_photo_url
data
registration_data

Validar que el campo password permita valores nulos:

DESCRIBE users;

En el modelo User, revisar que existan los campos en $fillable:

protected $fillable = [
    'name',
    'email',
    'profile_photo_url',
    'password',
    'fusionauth_id',
    'fusionauth_access_token',
    'fusionauth_refresh_token',
    'data',
    'registration_data',
];

También revisar que los campos JSON tengan casting:

protected $casts = [
    'data' => 'array',
    'registration_data' => 'array',
];

Finalmente, revisar el log de Laravel:

tail -f storage/logs/laravel.log

---

Error: Class not found

Problema

Laravel muestra un error similar a:

Class "SocialiteProviders\FusionAuth\FusionAuthExtendSocialite" not found

o

Class not found

Posibles causas

• No se instaló correctamente el paquete del provider de FusionAuth.
• Composer no actualizó el autoload.
• El provider fue registrado con un namespace incorrecto.
• El archivo EventServiceProvider.php tiene una referencia mal escrita.
• Solución recomendada

Validar que las dependencias estén instaladas:

composer show | grep fusionauth
composer show | grep socialite

Regenerar el autoload:

composer dump-autoload
php artisan optimize:clear

Revisar que en app/Providers/EventServiceProvider.php exista la siguiente configuración:

protected $listen = [
    \SocialiteProviders\Manager\SocialiteWasCalled::class => [
        \SocialiteProviders\FusionAuth\FusionAuthExtendSocialite::class . '@handle',
    ],
];