Solución de problemas de aplicaciones de Fabric

Diagnostique problemas comunes al desarrollar o implementar un proyecto de Fabric Apps. En este artículo se tratan los problemas relacionados con el inicio de sesión, los servicios locales, los cambios de esquema, el hospedaje estático y la CLI.

Problemas de implementación

La implementación falla con el error 401 o 403

Síntoma: La ejecución npx rayfin up devuelve un error de autenticación.

Causa: Su sesión de autenticación ha caducado o no ha iniciado sesión.

Solution:

Vuelva a autenticar y vuelva a intentar la implementación:

npx rayfin login
npx rayfin up

La implementación estática supera el límite de tamaño

Síntoma: Se produce un error de implementación de contenido estático con un error de límite de tamaño.

Causa: El archivo comprimido supera los 100 MB.

Solution:

Reduzca el tamaño de salida de la compilación por:

Excluir los mapas de código fuente de las compilaciones de producción
Optimización o eliminación de imágenes y vídeos grandes
Mover archivos binarios al almacenamiento en lugar de agruparlos
Verificar que la configuración del empaquetador excluya los artefactos de desarrollo

Problemas de autenticación.

Síntoma: Los usuarios se desconectan inmediatamente después de autenticarse.

Causa: El cliente no está configurado con la dirección URL base correcta ni la clave que se puede publicar.

Solution:

Compruebe que la configuración RayfinClient coincide con su backend:

const client = new RayfinClient({
  baseUrl: import.meta.env.VITE_RAYFIN_API_URL ?? 'http://localhost:5168',
  publishableKey: import.meta.env.VITE_RAYFIN_PUBLISHABLE_KEY,
});

Symptom: Browser bloquea la ventana del portal de Fabric durante el inicio de sesión.

Causa:ensureSignedInWithFabric() no se invocó desde un gestor de gestos del usuario.

Solution:

Llame a la función desde un controlador de eventos sincrónico:

async function handleClick() {
  await ensureSignedInWithFabric(client.auth, options);
}

// Attach to button click
<button onClick={handleClick}>Sign in</button>

Problemas del modelo de datos

Relaciones que no aparecen en la API

Síntoma: Los campos de entidad relacionados no están disponibles al realizar consultas.

Causa: Falta el decorador de navegación o no se aplicó el esquema.

Solution:

Compruebe que los decoradores de relaciones están presentes:
```
@one(() => Notebook) notebook?: Notebook;
```
Vuelva a aplicar el esquema.

La directiva de autorización no funciona

Síntoma: Los usuarios pueden acceder a los registros que no deberían ver.

Causa: La expresión de directiva es incorrecta o los nombres de las notificaciones no coinciden.

Solution:

Compruebe que la directiva usa nombres de notificación correctos (sub, email, role):
```
policy: (claims, item) => claims.sub.eq(item.user_id)
```
Registra el JWT decodificado para verificar que los valores de las declaraciones coincidan con los de tu código.

Respuestas de API obsoletas

Síntoma: Front-end devuelve formas de datos obsoletas después de los cambios de esquema.

Causa: La configuración generada se almacena en caché.

Solution:

Detenga el backend.
Elimine el .temp/ directorio en rayfin/:
```
rm -rf rayfin/.temp/
```
Reinicie los servicios y vuelva a aplicar el esquema.

Problemas de la CLI

No se encontró el comando

Síntoma: La ejecución npx rayfin devuelve "comando no encontrado".

Causa: La CLI no está instalada o npm no está en la ruta de acceso.

Solution:

Compruebe que Node.js y npm están instalados:
```
node --version
npm --version
```
Reinstale las dependencias:
```
npm install
```

Incompatibilidad de versión de la CLI

Síntoma: Los comandos de la CLI producen errores inesperados después de la actualización.

Causa: La versión de la CLI almacenada en caché está obsoleta.

Solution:

Actualice y vuelva a instalar:

npm update --save
npm install
npx rayfin --version

Discrepancia entre la versión global y la versión local de la CLI

Síntoma: Los comandos de la CLI producen errores inesperados en los proyectos.

Causa: Instalación global y local de las versiones de la CLI y no coinciden.

Solución: Validar la versión local npm list @microsoft/rayfin-cli. Esto muestra la versión de la node_modules del proyecto actual. Compruebe la versión global npm list -g @microsoft/rayfin-cli. Esto muestra la versión instalada en todo el sistema. Utiliza npm uninstall -g con el paquete Rayfin CLI para eliminar la versión global y usar tus versiones locales.

Problemas de compilación y empaquetado

Error en el comando de compilación

Síntoma: Se produce un error en la implementación de hospedaje estático porque el comando de compilación no produjo ninguna salida.

Causa: Errores de compilación o comando de compilación mal configurado.

Solution:

Ejecute el comando de compilación manualmente:
```
npm run build
```
Corrija los errores notificados.
Compruebe que la carpeta de salida contiene archivos.

Carpeta estática vacía

Síntoma: El despliegue estático falla con el mensaje de error «carpeta vacía».

Causa: La ruta de acceso configurada folder es incorrecta.

Solution:

Compruebe que la ruta de acceso de folder coincide con la salida de compilación de rayfin.yml:

services:
  staticHosting:
    folder: dist  # Verify this matches your build output
    buildCommand: npm run build

Problemas de la base de datos

Falla la aplicación del esquema de base de datos

Síntoma: Ejecutar npx rayfin up db apply o npx rayfin up db apply --force falla.

Causa: El esquema de la base de datos remota y el esquema definido en el código de la aplicación no están sincronizados. El código de la aplicación es la fuente de referencia para una aplicación de Fabric.

No modifiques el esquema remoto de la base de datos a través del portal Fabric, SQL Server Management Studio (SSMS), la extensión SQL Server para Visual Studio Code u otras herramientas SQL. No se soportan los siguientes cambios en las columnas de una entidad de datos:

Cambiar el nombre de una columna.
Cambiar el tipo de dato de una columna.
Eliminar una columna.

Se permite añadir una columna. Eliminar o modificar una columna existente puede romper la aplicación y su despliegue en Fabric.

Solution:

Revertir cualquier cambio manual en el esquema remoto de la base de datos para que coincida con el esquema del código de la app.
Si un agente codificador ha realizado un cambio de esquema no soportado en el código de la app, indícale que revierta ese cambio.
Ejecuta de nuevo el comando schema apply:
```
npx rayfin up db apply
```
Para un cambio de nombre de columna, --force podría permitir que la actualización del esquema se complete:
```
npx rayfin up db apply --force
```
Caution

El uso --force puede provocar una pérdida de datos permanente. Revisa las operaciones propuestas y confirma que aceptas el riesgo de pérdida de datos antes de continuar.

Conexión rechazada

Síntoma: Las operaciones de datos fallan con errores de conexión.

Causa: El contenedor de base de datos no se está ejecutando o se han producido errores en las comprobaciones de estado.

Solution:

Revise los registros de contenedor:
```
docker compose logs -f
```
Reinicie los servicios.

Pérdida de datos después del reinicio

Síntoma: Los datos desaparecen después de detener e iniciar los servicios.

Causa: Los volúmenes se eliminaron con --purge.

Solution:

Use --down en lugar de --purge para conservar los datos.

Limitaciones conocidas

Para conocer las limitaciones actuales y las soluciones alternativas recomendadas, consulte:

count() no está disponible en el cliente fluent GraphQL: use results.length.
No se admiten las relaciones de varios a varios: use una entidad de combinación explícita.
Los objetos Session son opacos; consulte las propiedades isAuthenticated o user.
Después de habilitar o deshabilitar la autenticación en rayfin.yml, reinicie el back-end.

Obtención de ayuda

Si el problema persiste:

Revise la documentación de Fabric Apps.
Compruebe el repositorio GitHub para ver si hay problemas conocidos.
Registre un informe de errores con registros detallados y pasos de reproducción.

Comentarios

¿Le ha resultado útil esta página?

Last updated on 2026-08-19

Solución de problemas de aplicaciones de Fabric

Problemas de implementación

La implementación falla con el error 401 o 403

La implementación estática supera el límite de tamaño

Problemas de autenticación.

La sesión no se mantiene después de iniciar sesión

Ventana emergente de SSO de Fabric bloqueada

Problemas del modelo de datos

Relaciones que no aparecen en la API

La directiva de autorización no funciona

Respuestas de API obsoletas

Problemas de la CLI

No se encontró el comando

Incompatibilidad de versión de la CLI

Discrepancia entre la versión global y la versión local de la CLI

Problemas de compilación y empaquetado

Error en el comando de compilación

Carpeta estática vacía

Problemas de la base de datos

Falla la aplicación del esquema de base de datos

Conexión rechazada

Pérdida de datos después del reinicio

Limitaciones conocidas

Obtención de ayuda

Contenido relacionado

Comentarios

Recursos adicionales