Résoudre les problèmes liés aux applications Fabric

Diagnostiquez les problèmes courants lorsque vous développez ou déployez un projet Fabric Apps. Cet article traite des problèmes liés à la connexion, aux services locaux, aux modifications de schéma, à l’hébergement statique et à l’interface CLI.

Problèmes de déploiement

Échec du déploiement avec l’erreur 401 ou 403

Symptôme: L’exécution npx rayfin up retourne une erreur d’authentification.

Cause : Votre session d’authentification a expiré ou vous n’êtes pas connecté.

Solution:

Réauthentifier et réessayer le déploiement :

npx rayfin login
npx rayfin up

Le déploiement statique dépasse la limite de taille

Symptôme: Le déploiement de contenu statique échoue avec une erreur de limite de taille.

Cause : L’archive compressée dépasse 100 Mo.

Solution:

Réduisez la taille de sortie de build par :

Exclusion des fichiers de mappage source des compilations de production
Optimisation ou suppression d’images et de vidéos volumineuses
Déplacement de fichiers binaires vers le stockage au lieu de les regrouper
La vérification de la configuration de votre bundler exclut les artefacts de développement

Le déploiement statique n’a pas de point de terminaison distant

Symptôme : Exécution npx rayfin up staticapp deploy de rapports indiquant qu’aucun point de terminaison distant n’est configuré.

Cause : Le déploiement statique uniquement met à jour un déploiement existant. Il ne peut pas déployer l’application distante initiale.

Solution:

Effectuez un déploiement complet une fois :

npx rayfin up

Après la fin du provisionnement, utilisez npx rayfin up staticapp deploy pour les mises à jour statiques suivantes.

Problèmes d’authentification

Échec de l’acquisition du token d’authentification

Symptôme :npx rayfin login ou une autre commande CLI authentifiée signale Failed to acquire authentication token ou une erreur de stockage des informations d’identification.

Cause : Le CLI n’est pas connecté, ou l’environnement ne fournit pas de stockage des identifiants soutenus par le système d’exploitation.

Solution:

Reconnectez-vous :

npx rayfin login

Pour un environnement de développement local restreint sans stockage d’identifiants, vous pouvez activer le plan de secours du chiffrement :

npx rayfin login --encryption-fallback-enabled

Warning

Le chiffrement de secours stocke le cache de jetons en texte clair. Utilisez-le uniquement dans un environnement de développement fiable. Ne l’utilisez pas en production ou en environnement partagé.

Symptôme: Les utilisateurs sont déconnectés immédiatement après l’authentification.

Cause : Le client n’est pas configuré avec l’URL de base correcte ou la clé modifiable.

Solution:

Vérifiez que la RayfinClient configuration correspond à votre back-end :

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 bloque la fenêtre du portail Fabric pendant la connexion.

Cause :ensureSignedInWithFabric() n’a pas été appelé à partir d’un gestionnaire de mouvements utilisateur.

Solution:

Appelez la fonction à partir d’un gestionnaire d’événements synchrone :

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

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

L’authentification Fabric expire

Symptôme : L’authentification Fabric échoue après cinq minutes.

Cause : Le portail Fabric n'a pas renvoyé le code de transfert avant l'expiration du flux.

Solution:

Vérifiez que returnOrigin correspond à l’origine de votre application, fermez la fenêtre contextuelle et relancez le processus de connexion.

Fabric SSO signale un décalage d’origine

Symptôme : La transmission SSO de Fabric rejette la réponse, car son origine ne correspond pas.

Cause :returnOrigin, allowedRedirectUris, ou fabricPortalUrl ne correspond pas à l'environnement où l'application et le portail Fabric tournent.

Solution:

Définissez returnOrigin sur l’origine de base de votre application.
Confirmez que l’origine apparaît dans services.auth.allowedRedirectUris.
Utilisez l’URL du portail Fabric pour l’environnement de production, de prévisualisation ou de développement approprié.
Exécutez npx rayfin up après avoir modifié rayfin.yml.

Pour plus d’informations, voir Configurer les URI de redirection d’authentification.

`initEmbeddedAuth()` retourne « `null` »

Symptôme : L’authentification intégrée ne crée pas de session.

Cause : Le SDK n'a pas détecté que l'application tourne dans Fabric.

Solution:

Incluez ?fabricEmbedded=true dans l’URL de l’application, ou définissez fabricEmbedded: true dans FabricAuthOptions.

L’authentification Fabric signale un décalage d’état

Symptôme : La connexion échoue car l’état de réponse ne correspond pas à l’état de la requête.

Cause : La réponse correspond à un flux expiré ou à une tentative de connexion précédente.

Solution:

Fermez la fenêtre Fabric et relancez le flux de connexion. Ne réutilisez pas les URL de rappel ou les valeurs d’état d’une tentative précédente.

Problèmes liés au modèle de données

L’API de données renvoie une erreur serveur interne après le déploiement

Symptôme :npx rayfin up ou npx rayfin up db apply réussit, mais l’API de données GraphQL ou REST renvoie une erreur interne du serveur.

Cause : Dans Microsoft SQL Server, un champ @text() sans max génère une colonne NVARCHAR(MAX), ce qui peut empêcher la génération du schéma GraphQL.

Solution:

Ajoutez une longueur maximale explicite à chaque champ de texte affecté :

@text({ max: 200 })
title!: string;

Ensuite, relisez et appliquez le changement de schéma :

npx rayfin up db apply --force

Avertissement

Examinez toutes les opérations signalées avant d’utiliser --force. Cette option peut entraîner une perte permanente de données.

Le service de données nécessite un dialecte

Symptôme : Le déploiement échoue avec une réponse HTTP 400 et signale Dialect is required when Data module is enabled.

Cause :services.data.enabled est true, mais rayfin.yml ne définit pas un dialecte.

Solution:

Configurez Microsoft SQL Server :

services:
  data:
    enabled: true
    dialect: mssql

La nouvelle entité n’est pas disponible après le déploiement

Symptôme : Le déploiement réussit, mais les requêtes contre une entité nouvelle ou modifiée échouent ou se comportent comme si l’entité n’existait pas.

Cause : Le schéma de la base de données peut toujours s’appliquer, ou bien le frontend peut utiliser des types générés obsolètes ou une configuration mise en cache.

Solution:

Vérifiez le déploiement :
```
npx rayfin up status
```
Attendez que le déploiement soit sain.
Rafraîchir ou reconstruire le frontend.
Si l’entité échoue toujours, appliquez explicitement le schéma :
```
npx rayfin up db apply
```

Pour le flux de travail complet, voir Appliquer et vérifier les modifications de schéma.

Relations non affichées dans l’API

Symptôme: Les champs d’entité associés ne sont pas disponibles lors de l’interrogation.

Cause : Le décorateur de navigation est manquant ou le schéma n’a pas été appliqué.

Solution:

Vérifiez que les décorateurs de relation sont présents :
```
@one(() => Notebook) notebook?: Notebook;
```
Réappliquez le schéma.

Stratégie d’autorisation ne fonctionne pas

Symptôme: Les utilisateurs peuvent accéder aux enregistrements qu’ils ne doivent pas voir.

Cause : L’expression de stratégie est incorrecte ou les noms de revendication ne correspondent pas.

Solution:

Vérifiez que la stratégie utilise les noms de revendication corrects (sub, email, role) :
```
policy: (claims, item) => claims.sub.eq(item.user_id)
```
Consignez le JWT décodé pour vérifier que les valeurs des revendications correspondent à votre code.

Réponses d’API obsolètes

Symptôme: Le serveur frontal retourne des formes de données obsolètes après les modifications du schéma.

Cause : La configuration générée est mise en cache.

Solution:

Arrêtez le backend.
Supprimez le .temp/ répertoire dans rayfin/:
```
rm -rf rayfin/.temp/
```
Redémarrez les services et réappliquez le schéma.

Problèmes liés à l’interface de ligne de commande

Commande introuvable

Symptôme: L’exécution npx rayfin retourne « commande introuvable ».

Cause : L’interface CLI n’est pas installée ou npm n’est pas dans votre chemin d’accès.

Solution:

Vérifiez que Node.js et npm sont installés :
```
node --version
npm --version
```
Réinstallez les dépendances :
```
npm install
```

Incompatibilité de version CLI

Symptôme: Les commandes CLI échouent avec des erreurs inattendues après la mise à jour.

Cause : La version de l’interface CLI mise en cache est obsolète.

Solution:

Mettre à jour et réinstaller :

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

Incompatibilité entre les versions globales et locales de la CLI

Symptôme: Les commandes CLI échouent avec des erreurs inattendues entre les projets.

Cause : Installation globale et locale des versions de l’interface CLI et elles ne correspondent pas.

Solution : Valider la version npm list @microsoft/rayfin-clilocale . Cela montre la version du node_modules de votre projet actuel. Vérifiez la version npm list -g @microsoft/rayfin-cliglobale. Cela montre la version installée à l’échelle du système. Utilisez npm uninstall -g le package Rayfin CLI pour supprimer la version globale et utiliser vos versions locales.

Problèmes de gestion secrète

La commande secrète ne s’invite pas

Symptôme :npx rayfin secret set <NAME> se ferme sans demander de saisir une valeur.

Cause : L’entrée standard n’est pas un terminal interactif, ou la variable d’environnement CI est définie à true. La commande utilise une invite interactive masquée.

Solution:

Utilisez l’une des alternatives suivantes prises en charge pour la création non interactive de secrets :

Définissez un secret en envoyant sa valeur à la commande :

Get-Content .\secret.txt | npx rayfin secret set <NAME> --stdin

Définissez plusieurs secrets à partir d’un fichier d’environnement :
```
npx rayfin secret set --env-file .\secrets.env
```

Gardez les valeurs secrètes hors de l’historique de votre shell et ne commettez pas secret.txt ou .\secrets.env dans le système de gestion de versions.

La commande secrète renvoie « permission refusée »

Symptôme :npx rayfin secret set ou npx rayfin secret list renvoie une erreur d’autorisation.

Cause : L'application n'est pas déployée, ou le compte connecté n'a pas accès à l'espace de travail Fabric cible.

Solution:

Exécutez npx rayfin up pour déployer l’application.
Exécutez npx rayfin login et sélectionnez un compte ayant accès à l’espace de travail.
Essaie à nouveau la commande secrète.

Pour plus d’informations, voir Gérer les secrets de fonction.

Problèmes de compilation et de mise en package

Échec de la commande Build

Symptôme: Échec du déploiement d’hébergement statique, car la commande de build n’a produit aucune sortie.

Cause : Erreurs de génération ou commande de build mal configurée.

Solution:

Exécutez la commande de build manuellement :
```
npm run build
```
Corrigez les erreurs signalées.
Vérifiez que le dossier de sortie contient des fichiers.

Dossier statique vide

Symptôme: Le déploiement statique échoue avec l’erreur « dossier vide ».

Cause : Le chemin d’accès configuré folder est incorrect.

Solution:

Vérifiez que le chemin d’accès folder correspond rayfin.yml à votre sortie de build :

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

Problèmes de base de données

Application du schéma de base de données échoue

Symptôme : L’exécution de npx rayfin up db apply ou de npx rayfin up db apply --force échoue.

Cause : Le schéma dans la base de données distante et le schéma défini dans le code de l’application sont désynchronisés. Le code de l’application est la source de vérité pour une application Fabric.

Ne modifiez pas le schéma de la base de données distante via le portail Fabric, SQL Server Management Studio (SSMS), l'extension SQL Server pour Visual Studio Code, ou d'autres outils SQL. Les modifications suivantes des colonnes dans une entité de données ne sont pas prises en charge :

Renommer une colonne.
Changer le type de données d’une colonne.
Enlever une colonne.

L’ajout d’une colonne est pris en charge. Supprimer ou modifier une colonne existante peut casser l’application et son déploiement sur Fabric.

Solution:

Annulez toute modification manuelle du schéma de la base de données distante afin qu’il corresponde au schéma du code de l’application.
Si un agent de codage a effectué un changement de schéma non pris en charge dans le code de l’application, demandez à l’agent de revenir en arrière ce changement.
Exécutez à nouveau la commande application du schéma :
```
npx rayfin up db apply
```
En cas de renommage de colonne, --force peut permettre à la mise à jour du schéma de s’effectuer :
```
npx rayfin up db apply --force
```
Avertissement

L’utilisation --force peut entraîner une perte de données permanente. Examinez les opérations proposées et assurez-vous d’accepter le risque de perte de données avant de procéder.

Connexion refusée

Symptôme: Les opérations de données échouent avec les erreurs de connexion.

Cause : Le conteneur de base de données n’est pas en cours d’exécution ou les vérifications d’intégrité ont échoué.

Solution:

Passez en revue les journaux de conteneur :
```
docker compose logs -f
```
Redémarrez les services.

Perte de données après le redémarrage

Symptôme: Les données disparaissent après l’arrêt et le démarrage des services.

Cause : Les volumes ont été supprimés avec --purge.

Solution:

Utilisez --down au lieu de --purge pour préserver les données.

Limitations connues

Pour connaître les limitations actuelles et les solutions de contournement recommandées, consultez :

count() n’est pas disponible sur le client Fluent GraphQL : utilisez results.length.
Les relations plusieurs-à-plusieurs ne sont pas prises en charge : utilisez une entité de jointure explicite.
Les objets de session sont opaques : vérifiez les propriétés isAuthenticated ou user.
Après avoir activé ou désactivé l’authentification dans rayfin.yml, redémarrez le serveur principal.

Obtenir de l’aide

Si le problème persiste :

Consultez la documentation Fabric Apps.
Vérifiez le dépôt GitHub pour connaître les problèmes connus.
Soumettez un rapport de bug avec des journaux détaillés et les étapes de reproduction.

Commentaires

Cette page a-t-elle été utile ?

Dernière mise à jour : 2026-09-29

Résoudre les problèmes liés aux applications Fabric

Problèmes de déploiement

Échec du déploiement avec l’erreur 401 ou 403

Le déploiement statique dépasse la limite de taille

Le déploiement statique n’a pas de point de terminaison distant

Problèmes d’authentification

Échec de l’acquisition du token d’authentification

Session non persistante après la connexion

fenêtre contextuelle d’authentification unique Fabric bloquée

L’authentification Fabric expire

Fabric SSO signale un décalage d’origine

initEmbeddedAuth() retourne « null »

L’authentification Fabric signale un décalage d’état

Problèmes liés au modèle de données

L’API de données renvoie une erreur serveur interne après le déploiement

Le service de données nécessite un dialecte

La nouvelle entité n’est pas disponible après le déploiement

Relations non affichées dans l’API

Stratégie d’autorisation ne fonctionne pas

Réponses d’API obsolètes

Problèmes liés à l’interface de ligne de commande

Commande introuvable

Incompatibilité de version CLI

Incompatibilité entre les versions globales et locales de la CLI

Problèmes de gestion secrète

La commande secrète ne s’invite pas

La commande secrète renvoie « permission refusée »

Problèmes de compilation et de mise en package

Échec de la commande Build

Dossier statique vide

Problèmes de base de données

Application du schéma de base de données échoue

Connexion refusée

Perte de données après le redémarrage

Limitations connues

Obtenir de l’aide

Contenu connexe

Commentaires

Ressources supplémentaires

`initEmbeddedAuth()` retourne « `null` »