# 🎯 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
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
php artisan route:list | grep autenticacion
```

Se debe verificar que existan rutas relacionadas con:

```bash
/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:

```sql
DESCRIBE users;
```

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

```php
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:

```php
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:

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

---

#### Error de configuración de services.php  


##### Problema

La aplicación no puede iniciar el flujo de autenticación o genera errores relacionados con configuraciones vacías.

##### Posibles causas  


- No existe la entrada fusionauth en config/services.php.
- Alguna variable del .env está vacía.
- Se modificó el nombre de una variable.
- El caché de configuración de Laravel sigue usando valores anteriores.

##### Solución recomendada

Validar que `config/services.php` tenga la siguiente estructura:

```php
'fusionauth' => [
    'client_id' => env('FUSIONAUTH_CLIENT_ID'),
    'client_secret' => env('FUSIONAUTH_CLIENT_SECRET'),
    'redirect' => env('FUSIONAUTH_REDIRECT_URI'),
    'base_url' => env('FUSIONAUTH_BASE_URL'),
    'tenant_id' => env('FUSIONAUTH_TENANT_ID'),
    'redirect_home' => env('FUSIONAUTH_REDIRECT_HOME'),
    'url_logout' => env('FUSIONAUTH_URL_LOGOUT'),
],
```

Después, revisar las variables en .env:

```
FUSIONAUTH_CLIENT_ID=tu_client_id
FUSIONAUTH_CLIENT_SECRET=tu_client_secret
FUSIONAUTH_REDIRECT_URI=${APP_URL}/autenticacion/callback
FUSIONAUTH_BASE_URL=https://acceso.tamaulipas.gob.mx
FUSIONAUTH_TENANT_ID=d9220956-99f7-431f-8de1-de37e65488a8
FUSIONAUTH_REDIRECT_HOME="/inicio"
FUSIONAUTH_URL_LOGOUT="${FUSIONAUTH_BASE_URL}/oauth2/logout?client_id=${FUSIONAUTH_CLIENT_ID}"
```

Limpiar configuración:

```
php artisan config:clear
php artisan optimize:clear
```

---

#### Error: Client ID o Client Secret incorrecto  


##### Problema

FusionAuth no permite completar el inicio de sesión o marca error relacionado con la aplicación cliente.

##### Posibles causas  


- FUSIONAUTH\_CLIENT\_ID incorrecto.
- FUSIONAUTH\_CLIENT\_SECRET incorrecto.
- Las credenciales corresponden a otra aplicación.
- El usuario intenta autenticarse contra un tenant o aplicación distinta.

##### Solución recomendada

Validar que los valores del .env correspondan exactamente a los configurados en FusionAuth:

```
FUSIONAUTH_CLIENT_ID=tu_client_id
FUSIONAUTH_CLIENT_SECRET=tu_client_secret
```

También confirmar que el usuario tenga acceso a la aplicación configurada en FusionAuth.

Después de modificar estas variables, ejecutar:

```
php artisan config:clear
php artisan optimize:clear
```

---

#### Error al guardar el usuario autenticado  


##### Problema

El login se completa en FusionAuth, pero Laravel no puede crear o actualizar el usuario en la base de datos.

##### Posibles causas  


- Falta el campo fusionauth\_id.
- fusionauth\_id está marcado como único y ya existe un usuario duplicado.
- El correo ya existe con otro fusionauth\_id.
- Faltan campos en $fillable.
- Las columnas JSON no existen o no son compatibles con la base de datos.
- Los tokens son demasiado largos para el tipo de columna definido.

##### Solución recomendada

Validar la estructura de la tabla:

```
DESCRIBE users;
```

Confirmar que los tokens estén definidos como `TEXT`:

```
fusionauth_access_token TEXT
fusionauth_refresh_token TEXT
```

Validar si ya existe el usuario:

```sql
SELECT id, name, email, fusionauth_id
FROM users
WHERE email = 'correo@dominio.gob.mx'
   OR fusionauth_id = 'id-de-fusionauth';
```

Si existe un conflicto de datos, revisar si corresponde actualizar el registro existente o depurar el registro duplicado.

---

#### Recomendación final

Si después de aplicar las soluciones anteriores el problema continúa, se recomienda recopilar la siguiente información antes de solicitar soporte:

- URL del sistema donde se presenta el error.
- Captura de pantalla del error.
- Fragmento relevante del archivo storage/logs/laravel.log.
- Valor configurado en APP\_URL.
- Valor configurado en FUSIONAUTH\_REDIRECT\_URI.
- Confirmación de que la URI de callback coincide con FusionAuth.
- Resultado de php artisan route:list | grep autenticacion.
- Confirmación de que la tabla users contiene los campos requeridos.

Con esta información será más sencillo identificar el origen del problema y aplicar una solución puntual.