Fehlerbehebung für Fabric-Apps

Diagnostizieren Sie häufige Probleme, wenn Sie ein Fabric Apps-Projekt entwickeln oder bereitstellen. In diesem Artikel werden Probleme mit der Anmeldung, lokalen Diensten, Schemaänderungen, statischem Hosting und der CLI behandelt.

Bereitstellungsprobleme

Die Bereitstellung schlägt mit dem Fehler 401 oder 403 fehl

Symptom: Beim Ausführen wird npx rayfin up ein Authentifizierungsfehler zurückgegeben.

Ursache: Ihre Authentifizierungssitzung ist abgelaufen oder Sie sind nicht angemeldet.

Solution:

Erneutes Authentifizieren und Wiederholen der Bereitstellung:

npx rayfin login
npx rayfin up

Statisches Deployment überschreitet das Größenlimit.

Symptom: Die Bereitstellung statischer Inhalte schlägt mit einem Größengrenzwertfehler fehl.

Ursache: Das komprimierte Archiv überschreitet 100 MB.

Solution:

Reduzieren Sie die Größe der Build-Ausgabe um:

Source-Maps aus Produktions-Builds ausschließen
Optimieren oder Entfernen großer Bilder und Videos
Verschieben von Binärdateien in den Speicher, anstatt sie zu bündeln
Überprüfen, ob die Bundler-Konfiguration Entwicklungsartefakte ausschließt

Authentifizierungsprobleme

Symptom: Benutzer werden unmittelbar nach der Authentifizierung abgemeldet.

Ursache: Der Client ist nicht mit der richtigen Basis-URL oder dem Veröffentlichungsschlüssel konfiguriert.

Solution:

Überprüfen Sie, ob die RayfinClient Konfiguration Ihrem Back-End entspricht:

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 blockiert das Fabric Portalfenster während der Anmeldung.

Ursache:ensureSignedInWithFabric() wurde nicht von einem Benutzergestenhandler aufgerufen.

Solution:

Aufrufen der Funktion aus einem synchronen Ereignishandler:

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

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

Datenmodellprobleme

Beziehungen, die nicht in der API angezeigt werden

Symptom: Verwandte Entitätsfelder sind beim Abfragen nicht verfügbar.

Ursache: Der Navigationsdekoror fehlt, oder das Schema wurde nicht angewendet.

Solution:

Überprüfen Sie, ob die Beziehungsdekoratoren vorhanden sind:
```
@one(() => Notebook) notebook?: Notebook;
```
Erneutes Anwenden des Schemas.

Autorisierungsrichtlinie funktioniert nicht

Symptom: Benutzer können auf Datensätze zugreifen, die sie nicht sehen sollten.

Ursache: Der Richtlinienausdruck ist falsch, oder die Anspruchsnamen stimmen nicht überein.

Solution:

Überprüfen Sie, ob die Richtlinie die richtigen Anspruchsnamen verwendet (sub, email, role):
```
policy: (claims, item) => claims.sub.eq(item.user_id)
```
Protokollieren Sie die dekodierte JWT, um zu überprüfen, ob die Claim-Werte mit Ihrem Code übereinstimmen.

Veraltete API-Antworten

Symptom: Frontend gibt veraltete Daten-Shapes nach Schemaänderungen zurück.

Ursache: Die generierte Konfiguration wird zwischengespeichert.

Solution:

Stoppen Sie das Backend.
Löschen Sie das .temp/ Verzeichnis in rayfin/:
```
rm -rf rayfin/.temp/
```
Starten Sie die Dienste neu und wenden Sie das Schema erneut an.

CLI-Probleme

Befehl nicht gefunden

Symptom: Wird ausgeführt npx rayfin , wird "Befehl nicht gefunden" zurückgegeben.

Ursache: Die CLI ist nicht installiert, oder npm befindet sich nicht in Ihrem PATH.

Solution:

Überprüfen Sie, Node.js und npm installiert sind:
```
node --version
npm --version
```
Installieren Sie Abhängigkeiten neu:
```
npm install
```

CLI-Versionskonflikt

Symptom: CLI-Befehle schlagen nach dem Aktualisieren mit unerwarteten Fehlern fehl.

Ursache: Die zwischengespeicherte CLI-Version ist veraltet.

Solution:

Aktualisieren und erneutes Installieren:

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

Globale und lokale Missübereinstimmung der CLI-Versionen

Symptom: CLI-Befehle schlagen bei unerwarteten Fehlern in Projekten fehl.

Ursache: Globale und lokale Installation der CLI-Versionen und stimmen nicht überein.

Lösung: Überprüfen der lokalen Version npm list @microsoft/rayfin-cli. Dies zeigt die Version im node_modules Ihres aktuellen Projekts an. Überprüfen Sie die globale Version npm list -g @microsoft/rayfin-cli. Dies zeigt die systemweit installierte Version an. Verwenden Sie npm uninstall -g das Rayfin CLI-Paket, um die globale Version zu entfernen und Ihre lokalen Versionen zu verwenden.

Build- und Paketierungsprobleme

Buildbefehl schlägt fehl

Symptom: Fehler bei der statischen Hostingbereitstellung, da der Buildbefehl keine Ausgabe erzeugt hat.

Ursache: Buildfehler oder falsch konfigurierter Buildbefehl.

Solution:

Führen Sie den Buildbefehl manuell aus:
```
npm run build
```
Beheben Sie alle gemeldeten Fehler.
Überprüfen Sie, ob der Ausgabeordner Dateien enthält.

Leerer statischer Ordner

Symptom: Die statische Bereitstellung schlägt mit dem Fehler "Leerer Ordner" fehl.

Ursache: Der konfigurierte folder Pfad ist falsch.

Solution:

Überprüfen Sie, ob der Pfad folder in rayfin.yml mit Ihrer Build-Ausgabe übereinstimmt:

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

Datenbankprobleme

Anwenden des Datenbankschemas schlägt fehl

Symptom: Das Ausführen von npx rayfin up db apply oder npx rayfin up db apply --force schlägt fehl.

Ursache: Das Schema in der entfernten Datenbank und das im App-Code definierte Schema sind nicht synchron. Der App-Code ist die Wahrheitsquelle für eine Fabric-App.

Ändern Sie das entfernte Datenbankschema nicht über das Fabric-Portal, SQL Server Management Studio (SSMS), die SQL Server-Erweiterung für Visual Studio Code oder andere SQL-Tools. Die folgenden Änderungen an Spalten in einer Datenentität werden nicht unterstützt:

Eine Kolumne umbenennen.
Änderung des Datentyps einer Spalte.
Eine Säule entfernen.

Das Hinzufügen einer Spalte wird unterstützt. Das Entfernen oder Ändern einer bestehenden Spalte kann die App und ihre Bereitstellung auf Fabric beeinträchtigen.

Solution:

Setze alle manuellen Änderungen am entfernten Datenbankschema so zurück, dass es mit dem Schema im App-Code übereinstimmt.
Wenn ein Codieragent eine nicht unterstützte Schemaänderung im App-Code vorgenommen hat, beauftragen Sie den Agenten, diese Änderung rückgängig zu machen.
Führe den Befehl schema apply erneut aus:
```
npx rayfin up db apply
```
Beim Umbenennen einer Spalte könnte --force die Schemaaktualisierung abschließen lassen:
```
npx rayfin up db apply --force
```
Vorsicht

Die Verwendung --force kann zu einem dauerhaften Datenverlust führen. Überprüfen Sie die vorgeschlagenen Operationen und bestätigen Sie, dass Sie das Datenverlustrisiko akzeptieren, bevor Sie fortfahren.

Verbindung verweigert

Symptom: Datenvorgänge schlagen mit Verbindungsfehlern fehl.

Ursache: Der Datenbankcontainer läuft nicht, oder die Zustandsprüfungen sind fehlgeschlagen.

Solution:

Überprüfen von Containerprotokollen:
```
docker compose logs -f
```
Starten Sie Dienste neu.

Datenverlust nach dem Neustart

Symptom: Daten verschwinden nach dem Beenden und Neustarten von Diensten.

Ursache: Volumes wurden mit --purge gelöscht.

Solution:

Verwenden Sie --down anstelle von --purge, um Daten zu erhalten.

Bekannte Einschränkungen

Aktuelle Einschränkungen und empfohlene Problemumgehungen finden Sie unter:

count() ist im Fluent GraphQL-Client nicht verfügbar – verwenden Sie results.length.
Viele-zu-viele-Beziehungen werden nicht unterstützt – verwenden Sie eine explizite Join-Entität.
Sitzungsobjekte sind opak – prüfen Sie die Eigenschaften isAuthenticated oder user.
Nachdem Sie die Authentifizierung in rayfin.yml aktiviert oder deaktiviert haben, starten Sie das Backend neu.

Hilfe erhalten

Falls das Problem weiterhin besteht:

Lesen Sie die Dokumentation Fabric Apps.
Überprüfen Sie das Repository GitHub auf bekannte Probleme.
Erstellen Sie einen Fehlerbericht mit detaillierten Protokollen und Reproduktionsschritten.

Feedback

War diese Seite hilfreich?

Last updated on 2026-08-19

Fehlerbehebung für Fabric-Apps

Bereitstellungsprobleme

Die Bereitstellung schlägt mit dem Fehler 401 oder 403 fehl

Statisches Deployment überschreitet das Größenlimit.

Authentifizierungsprobleme

Sitzung nach der Anmeldung nicht beibehalten

Fabric SSO-Popup blockiert

Datenmodellprobleme

Beziehungen, die nicht in der API angezeigt werden

Autorisierungsrichtlinie funktioniert nicht

Veraltete API-Antworten

CLI-Probleme

Befehl nicht gefunden

CLI-Versionskonflikt

Globale und lokale Missübereinstimmung der CLI-Versionen

Build- und Paketierungsprobleme

Buildbefehl schlägt fehl

Leerer statischer Ordner

Datenbankprobleme

Anwenden des Datenbankschemas schlägt fehl

Verbindung verweigert

Datenverlust nach dem Neustart

Bekannte Einschränkungen

Hilfe erhalten

Verwandte Inhalte

Feedback

Zusätzliche Ressourcen