Problemen met Fabric apps oplossen

Veelvoorkomende problemen vaststellen bij het ontwikkelen of implementeren van een Fabric Apps-project. In dit artikel worden problemen behandeld met aanmelding, lokale services, schemawijzigingen, statische hosting en de CLI.

Implementatieproblemen

Uitrol mislukt met fout 401 of 403

Symptoom: Uitvoeren npx rayfin up retourneert een verificatiefout.

Oorzaak: Uw verificatiesessie is verlopen of u bent niet aangemeld.

Oplossing:

De implementatie opnieuw verifiëren en opnieuw uitvoeren:

npx rayfin login
npx rayfin up

Statische implementatie overschrijdt de groottelimiet

Symptoom: Implementatie van statische inhoud mislukt met een groottelimietfout.

Oorzaak: Het gecomprimeerde archief overschrijdt 100 MB.

Oplossing:

Verklein de uitvoergrootte van de build door:

Brontoewijzingen uitsluiten van productieversies
Grote afbeeldingen en video's optimaliseren of verwijderen
Binaire bestanden verplaatsen naar opslag in plaats van ze te bundelen
Controleren of uw bundelconfiguratie ontwikkelingsartefacten uitsluit

Statische implementatie heeft geen extern eindpunt

Symptoom: Bij het uitvoeren van npx rayfin up staticapp deploy wordt gemeld dat er geen extern eindpunt is ingesteld.

Oorzaak: Een implementatie met alleen statische bestanden werkt een bestaande implementatie bij. Het kan de initiële externe app niet provisioneren.

Oplossing:

Voer één keer een volledige uitrol uit:

npx rayfin up

Na voltooiing van de inrichting gebruik je npx rayfin up staticapp deploy voor latere updates die alleen statische inhoud betreffen.

Verificatieproblemen

Het verkrijgen van een authenticatietoken mislukt

Symptoom:npx rayfin login of een andere geauthenticeerde CLI-commandorapporten Failed to acquire authentication token of een fout bij het opslaan van inloggegevens.

Oorzaak: De CLI is niet ingelogd, of de omgeving biedt geen inloggegevens die door het besturingssysteem worden ondersteund.

Oplossing:

Opnieuw inloggen:

npx rayfin login

Voor een beperkte lokale ontwikkelomgeving zonder opslag van inloggegevens kun je de encryptie-fallback inschakelen:

npx rayfin login --encryption-fallback-enabled

Warning

De terugvaloptie voor versleuteling slaat de token-cache op in platte tekst. Gebruik het alleen in een vertrouwde ontwikkelomgeving. Gebruik het niet in productie of gedeelde omgevingen.

Symptoom: Gebruikers worden onmiddellijk na verificatie afgemeld.

Oorzaak: De client is niet geconfigureerd met de juiste basis-URL of publiceerbare sleutel.

Oplossing:

Controleer of de RayfinClient configuratie overeenkomt met uw 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 blokkeert het Fabric portalvenster tijdens het aanmelden.

Oorzaak:ensureSignedInWithFabric() werd niet aangeroepen vanuit een handler voor gebruikersbewegingen.

Oplossing:

Roep de functie aan vanuit een synchrone gebeurtenis-handler:

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

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

Fabric-authenticatie loopt uit

Symptoom: Fabric-authenticatie faalt na vijf minuten.

Oorzaak: Het Fabric-portaal gaf de overdrachtscode niet terug voordat de flow was verlopen.

Oplossing:

Bevestig dat dit returnOrigin overeenkomt met de oorsprong van je app, sluit de pop-up en start de aanmeldproces opnieuw.

Fabric SSO meldt een afwijkende herkomst

Symptoom: De Fabric SSO-overdracht wijst het antwoord af omdat de oorsprong niet overeenkomt.

Oorzaak:returnOrigin, allowedRedirectUris, of fabricPortalUrl niet overeenkomt met de omgeving waar de app en het Fabric-portaal draaien.

Oplossing:

Stel returnOrigin in op de pure origin van je app.
Bevestig dat de oorsprong voorkomt in services.auth.allowedRedirectUris.
Gebruik de URL van het Fabric-portaal voor de juiste productie-, preview- of ontwikkelomgeving.
Voer npx rayfin up uit na het wijzigen van rayfin.yml.

Voor meer informatie, zie Authenticatie redirect URI's configureren.

`initEmbeddedAuth()` geeft `null` terug

Symptoom: Embedded authenticatie creëert geen sessie.

Oorzaak: De SDK heeft niet gedetecteerd dat de app binnen Fabric draait.

Oplossing:

Neem ?fabricEmbedded=true op in de app-URL, of stel fabricEmbedded: true in in FabricAuthOptions.

Fabric-authenticatie meldt een statusconflict

Symptoom: Inloggen mislukt omdat de responsstatus niet overeenkomt met de verzoekstatus.

Oorzaak: De reactie behoort tot een verlopen flow of een eerdere inlogpoging.

Oplossing:

Sluit de Fabric-popup en start de aanmeldstroom opnieuw. Gebruik geen callback-URL's of statuswaarden van een eerdere poging.

Problemen met gegevensmodellen

Data API geeft na de implementatie een interne serverfout terug

Symptoom:npx rayfin up of npx rayfin up db apply slaagt, maar de GraphQL- of REST-data-API geeft een interne serverfout terug.

Oorzaak: Op Microsoft SQL Server genereert een @text() veld zonder max een NVARCHAR(MAX) kolom, wat het genereren van GraphQL-schema's kan voorkomen.

Oplossing:

Voeg een expliciete maximale lengte toe aan elk getroffen tekstveld:

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

Bekijk en pas vervolgens de schemawijziging toe:

npx rayfin up db apply --force

Caution

Controleer alle gemelde bewerkingen voordat je --force gebruikt. De optie kan permanent dataverlies veroorzaken.

Dataservice vereist een dialect

Symptoom: Implementatie mislukt met een HTTP 400-respons en rapporteert Dialect is required when Data module is enabled.

Oorzaak:services.data.enabled is true, maar rayfin.yml definieert geen dialect.

Oplossing:

Microsoft SQL Server configureren:

services:
  data:
    enabled: true
    dialect: mssql

Nieuwe entiteit is niet beschikbaar na de uitrol

Symptoom: De implementatie slaagt, maar vragen tegen een nieuwe of gewijzigde entiteit falen of gedragen zich alsof de entiteit niet bestaat.

Oorzaak: Het databaseschema kan nog steeds van toepassing zijn, of de frontend gebruikt verouderde gegenereerde types of gecachete configuraties.

Oplossing:

Bekijk de inzet:
```
npx rayfin up status
```
Wacht tot de uitrol gezond is.
Vernieuw of bouw de frontend opnieuw.
Als de entiteit nog steeds faalt, pas het schema expliciet toe:
```
npx rayfin up db apply
```

Voor de volledige workflow, zie Schemawijzigingen toepassen en verifiëren.

Relaties worden niet weergegeven in API

Symptoom: Gerelateerde entiteitsvelden zijn niet beschikbaar bij het uitvoeren van query's.

Oorzaak: De navigatie-decorator ontbreekt of het schema is niet toegepast.

Oplossing:

Controleer of de relatie-decorators aanwezig zijn:
```
@one(() => Notebook) notebook?: Notebook;
```
Het schema opnieuw gebruiken.

Autorisatiebeleid werkt niet

Symptoom: Gebruikers hebben toegang tot records die ze niet mogen zien.

Oorzaak: De beleidsexpressie is onjuist of de claimnamen komen niet overeen.

Oplossing:

Controleer of het beleid de juiste claimnamen gebruikt (sub, email, role):
```
policy: (claims, item) => claims.sub.eq(item.user_id)
```
Leg de gedecodeerde JWT vast om te controleren of de waarden van de claims overeenkomen met uw code.

Verlopen API-antwoorden

Symptoom: Front-end retourneert verouderde gegevensshapes nadat het schema is gewijzigd.

Oorzaak: De gegenereerde configuratie wordt in de cache opgeslagen.

Oplossing:

Stop de backend.
Verwijder de .temp/ map in rayfin/:
```
rm -rf rayfin/.temp/
```
Start de services opnieuw op en past het schema opnieuw toe.

CLI-problemen

De opdracht is niet gevonden

Symptoom: Als u de opdracht npx rayfin uitvoert, wordt 'opdracht niet gevonden' geretourneerd.

Oorzaak: De CLI is niet geïnstalleerd of npm bevindt zich niet in uw PATH.

Oplossing:

Controleer of Node.js en npm zijn geïnstalleerd:
```
node --version
npm --version
```
Afhankelijkheden opnieuw installeren:
```
npm install
```

CLI-versie komt niet overeen

Symptoom: CLI-opdrachten mislukken met onverwachte fouten na het bijwerken.

Oorzaak: Cli-versie met cache is verouderd.

Oplossing:

Bijwerken en opnieuw installeren:

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

CLI globale en lokale versie-mismatch

Symptoom: CLI-opdrachten mislukken met onverwachte fouten in projecten.

Oorzaak: Globale en lokale installatie van de CLI-versies en deze komen niet overeen.

Oplossing: Lokale versie npm list @microsoft/rayfin-clivalideren. Hier ziet u de versie in de node_modules van uw huidige project. Controleer de algemene versie npm list -g @microsoft/rayfin-cli. Hier ziet u de versie die op het hele systeem is geïnstalleerd. Gebruik npm uninstall -g het Rayfin CLI-pakket om de globale versie te verwijderen en uw lokale versies te gebruiken.

Problemen met geheim beheer

Secret command geeft geen prompt

Symptoom:npx rayfin secret set <NAME> Vertrekt zonder om een waarde te vragen.

Oorzaak: Standaard invoer is geen interactieve terminal, of de CI omgevingsvariabele is ingesteld op true. Het commando gebruikt een gemaskeerde interactieve prompt.

Oplossing:

Gebruik een van de volgende ondersteunde alternatieven voor het creëren van niet-interactieve geheimen:

Stel een geheim in door de waarde via een pipe door te geven aan het commando:
```
Get-Content .\secret.txt | npx rayfin secret set <NAME> --stdin
```
Stel meerdere geheimen in vanuit een omgevingsbestand:
```
npx rayfin secret set --env-file .\secrets.env
```

Houd geheime waarden uit je shellgeschiedenis en commit .\secrets.env niet en neem secret.txt niet op in versiebeheer.

Geheim commando retourneert toegang geweigerd

Symptoom:npx rayfin secret set of npx rayfin secret list geeft een machtigingsfout.

Oorzaak: De app is niet geïmplementeerd, of het aangemelde account heeft geen toegang tot de beoogde Fabric-werkruimte.

Oplossing:

Start npx rayfin up om de app te provisioneren.
Start npx rayfin login en selecteer een account met toegang tot de werkruimte.
Probeer het geheime commando opnieuw.

Voor meer informatie, zie Functiegeheimen beheren.

Problemen met bouwen en verpakken

Build-opdracht mislukt

Symptoom: De implementatie van statische hosting mislukt omdat de buildopdracht geen uitvoer heeft geproduceerd.

Oorzaak: Buildfouten of onjuist geconfigureerde build-opdracht.

Oplossing:

Voer de buildopdracht handmatig uit:
```
npm run build
```
Los eventuele gerapporteerde fouten op.
Controleer of de uitvoermap bestanden bevat.

Lege map voor statische bestanden

Symptoom: Statische uitrol mislukt met de foutmelding 'lege map'.

Oorzaak: Het geconfigureerde folder pad is onjuist.

Oplossing:

Controleer of het pad folder in rayfin.yml overeenkomt met uw build-uitvoer:

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

Databaseproblemen

Toepassen van databaseschema mislukt

Symptoom: Het uitvoeren van npx rayfin up db apply of npx rayfin up db apply --force mislukt.

Oorzaak: Het schema in de externe database en het schema dat in de app-code is gedefinieerd, zijn niet synchroon. De appcode is de bron van waarheid voor een Fabric-app.

Pas het externe databaseschema niet aan via het Fabric-portaal, SQL Server Management Studio (SSMS), de SQL Server-extensie voor Visual Studio Code, of andere SQL-tools. De volgende wijzigingen in kolommen in een data-entiteit worden niet ondersteund:

Een column hernoemen.
Het datatype van een kolom wijzigen.
Een kolom verwijderen.

Het toevoegen van een kolom wordt ondersteund. Het verwijderen of wijzigen van een bestaande kolom kan de app en de implementatie ervan naar Fabric breken.

Oplossing:

Draai alle handmatige wijzigingen aan het externe databaseschema terug zodat het overeenkomt met het schema in de app-code.
Als een codeeragent een niet-ondersteunde schemawijziging in de appcode heeft aangebracht, geef dan opdracht aan de agent om die wijziging terug te draaien.
Voer het schema apply-commando opnieuw uit:
```
npx rayfin up db apply
```
Bij het hernoemen van een kolom kan --force ervoor zorgen dat de schema-update wordt voltooid:
```
npx rayfin up db apply --force
```
Caution

Het gebruik --force kan leiden tot permanent gegevensverlies. Bekijk de voorgestelde operaties en bevestig dat u het risico op dataverlies accepteert voordat u verder gaat.

Verbinding geweigerd

Symptoom: Gegevensbewerkingen mislukken met verbindingsfouten.

Oorzaak: De databasecontainer wordt niet uitgevoerd of statuscontroles zijn mislukt.

Oplossing:

Containerlogboeken controleren:
```
docker compose logs -f
```
Start de services opnieuw op.

Gegevensverlies na opnieuw opstarten

Symptoom: Gegevens verdwijnen na het stoppen en starten van services.

Oorzaak: Volumes zijn verwijderd met --purge.

Oplossing:

Gebruik --down in plaats van --purge gegevens te bewaren.

Bekende beperkingen

Zie voor huidige beperkingen en aanbevolen tijdelijke oplossingen:

count() is niet beschikbaar op de Fluent GraphQL-client, gebruik results.length.
Veel-op-veel-relaties worden niet ondersteund. Gebruik een expliciete join-entiteit.
Sessieobjecten zijn ondoorzichtig: controleer isAuthenticated of user eigenschappen.
Nadat u authenticatie in rayfin.yml hebt ingeschakeld of uitgeschakeld, start u de backend opnieuw.

Hulp krijgen

Als het probleem aanhoudt:

Raadpleeg de documentatie Fabric Apps.
Controleer de opslagplaats GitHub op bekende problemen.
Dien een foutenrapport in met gedetailleerde logboeken en reproductiestappen.

Feedback

Is deze pagina nuttig?

Laatst bijgewerkt om 2026-09-29

Problemen met Fabric apps oplossen

Implementatieproblemen

Uitrol mislukt met fout 401 of 403

Statische implementatie overschrijdt de groottelimiet

Statische implementatie heeft geen extern eindpunt

Verificatieproblemen

Het verkrijgen van een authenticatietoken mislukt

Sessie wordt niet behouden na inloggen

Fabric SSO-popup geblokkeerd

Fabric-authenticatie loopt uit

Fabric SSO meldt een afwijkende herkomst

initEmbeddedAuth() geeft null terug

Fabric-authenticatie meldt een statusconflict

Problemen met gegevensmodellen

Data API geeft na de implementatie een interne serverfout terug

Dataservice vereist een dialect

Nieuwe entiteit is niet beschikbaar na de uitrol

Relaties worden niet weergegeven in API

Autorisatiebeleid werkt niet

Verlopen API-antwoorden

CLI-problemen

De opdracht is niet gevonden

CLI-versie komt niet overeen

CLI globale en lokale versie-mismatch

Problemen met geheim beheer

Secret command geeft geen prompt

Geheim commando retourneert toegang geweigerd

Problemen met bouwen en verpakken

Build-opdracht mislukt

Lege map voor statische bestanden

Databaseproblemen

Toepassen van databaseschema mislukt

Verbinding geweigerd

Gegevensverlies na opnieuw opstarten

Bekende beperkingen

Hulp krijgen

Verwante inhoud

Feedback

Aanvullende resources

`initEmbeddedAuth()` geeft `null` terug