Feilsøking av Fabric-apper

Diagnostiser vanlige problemer når du utvikler eller distribuerer et Fabric Apps-prosjekt. Denne artikkelen tar for seg problemer med innlogging, lokale tjenester, skjemaendringer, statisk hosting og CLI.

Utplasseringsproblemer

Utrulling feiler med 401- eller 403-feil

Symptom: Kjøring npx rayfin up gir en autentiseringsfeil.

Årsak: Autentiseringsøkten din utløp eller du er ikke innlogget.

Løsning:

Autentiser på nytt og prøv utplasseringen på nytt:

npx rayfin login
npx rayfin up

Statisk utrulling overstiger størrelsesgrensen

Symptom: Statisk innholdsdistribusjon feiler med en størrelsesbegrensningsfeil.

Årsak: Det komprimerte arkivet overstiger 100 MB.

Løsning:

Reduser byggeutdata ved å:

Ekskludering av kildekart fra produksjonsbygg
Optimalisering eller fjerning av store bilder og videoer
Flytte binære filer til lagring i stedet for å pakke dem sammen
Å verifisere bundler-konfigurasjonen din utelukker utviklingsartefakter

Statisk utrulling har ingen ekstern endepunkt

Symptom: Kjøring npx rayfin up staticapp deploy rapporterer at ingen ekstern endepunkt er konfigurert.

Årsak: Kun statisk utrulling oppdaterer en eksisterende utrulling. Den klarer ikke å provisionere den første eksterne appen.

Løsning:

Kjør en full utrulling én gang:

npx rayfin up

Etter at provisjonen er fullført, bruk npx rayfin up staticapp deploy den for påfølgende statiske oppdateringer.

Godkjenningsproblemer

Innhenting av autentiseringstoken feiler

Symptom:npx rayfin login eller en annen autentisert CLI-kommandorapport Failed to acquire authentication token eller en feil ved lagring av legitimasjon.

Årsak: CLI-en er ikke logget inn, eller miljøet tilbyr ikke operativsystemstøttet legitimasjonslagring.

Løsning:

Logg inn igjen:

npx rayfin login

For et begrenset lokalt utviklingsmiljø uten legitimasjonslagring kan du aktivere krypteringsfallback:

npx rayfin login --encryption-fallback-enabled

Advarsel!

Krypterings-fallback lagrer token-cachen i klartekst. Bruk det kun i et pålitelig utviklingsmiljø. Ikke bruk det i produksjon eller delte miljøer.

Symptom: Brukere logges ut umiddelbart etter autentisering.

Årsak: Klienten er ikke konfigurert med riktig grunn-URL eller publiserbar nøkkel.

Løsning:

Sjekk at konfigurasjonen matcher RayfinClient backend-en din:

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

Symptom: Nettleseren blokkerer Fabric portalvinduet under innlogging.

Årsak:ensureSignedInWithFabric() ble ikke kalt fra en bruker-gest-håndterer.

Løsning:

Kall funksjonen fra en synkron hendelseshåndterer:

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

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

Fabric-autentisering går ut på tid

Symptom: Fabric-autentisering feiler etter fem minutter.

Årsak: Fabric-portalen returnerte ikke overleveringskoden før flyten utløp.

Løsning:

Bekreft at det returnOrigin samsvarer med appens opprinnelse, lukk popup-vinduet, og start innloggingsflyten på nytt.

Fabric SSO rapporterer om opprinnelsesmismatch

Symptom: Fabric SSO-overleveringen avviser responsen fordi opprinnelsen ikke stemmer overens.

Årsak:returnOrigin, allowedRedirectUris, eller fabricPortalUrl samsvarer ikke med miljøet der appen og Fabric-portalen kjører.

Løsning:

Sett returnOrigin til appens bare opprinnelse.
Bekreft at origo vises i services.auth.allowedRedirectUris.
Bruk Fabric-portalens URL for riktig produksjons-, forhåndsvisnings- eller utviklingsmiljø.
Løp npx rayfin up etter å ha skiftet rayfin.yml.

For mer informasjon, se Konfigurer autentiseringsomdirigerings-URI-er.

`initEmbeddedAuth()` Returer `null`

Symptom: Innebygd autentisering oppretter ikke en økt.

Årsak: SDK-en oppdaget ikke at appen kjører inne i Fabric.

Løsning:

Inkluder ?fabricEmbedded=true URL-en i appen, eller sett fabricEmbedded: true i FabricAuthOptions.

Fabric-autentisering rapporterer en tilstandsmismatch

Symptom: Innlogging feiler fordi responstilstanden ikke samsvarer med forespørselstilstanden.

Årsak: Svaret tilhører en utløpt flyt eller et tidligere innloggingsforsøk.

Løsning:

Lukk Fabric-popupen og start påloggingsflyten på nytt. Ikke gjenbruk callback-URL-er eller tilstandsverdier fra et tidligere forsøk.

Datamodellproblemer

Data API returnerer en intern serverfeil etter utrulling

Symptom:npx rayfin up eller npx rayfin up db apply lykkes, men GraphQL- eller REST-data-API-et returnerer en intern serverfeil.

Årsak: På Microsoft SQL Server genererer et @text() felt uten max en NVARCHAR(MAX) kolonne, noe som kan forhindre generering av GraphQL-skjemaer.

Løsning:

Legg til en eksplisitt maksimal lengde på hvert berørte tekstfelt:

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

Deretter gjennomgår og anvender du skjemaendringen:

npx rayfin up db apply --force

Forsiktig!

Gå gjennom alle rapporterte operasjoner før du bruker --force. Alternativet kan føre til permanent datatap.

Datatjeneste krever en dialekt

Symptom: Utrulling feiler med et HTTP 400-svar og rapporterer Dialect is required when Data module is enabled.

Årsak:services.data.enabled er true, men rayfin.yml definerer ikke en dialekt.

Løsning:

Konfigurer Microsoft SQL Server:

services:
  data:
    enabled: true
    dialect: mssql

Ny enhet er ikke tilgjengelig etter utrulling

Symptom: Distribusjonen lykkes, men forespørsler mot en ny eller endret enhet feiler eller oppfører seg som om enheten ikke eksisterer.

Årsak: Databaseskjemaet kan fortsatt gjelde, eller frontenden kan bruke utdaterte genererte typer eller bufret konfigurasjon.

Løsning:

Sjekk utplasseringen:
```
npx rayfin up status
```
Vent til utplasseringen er frisk.
Oppdater eller bygg opp frontenden på nytt.
Hvis enheten fortsatt feiler, bruk skjemaet eksplisitt:
```
npx rayfin up db apply
```

For hele arbeidsflyten, se Bruk og verifiser skjemaendringer.

Relasjoner som ikke vises i API-et

Symptom: Relaterte entitetsfelt er ikke tilgjengelige ved forespørsler.

Årsak: Navigasjonsdekoratoren mangler, eller skjemaet ble ikke brukt.

Løsning:

Sjekk at forholdsdekoratørene er til stede:
```
@one(() => Notebook) notebook?: Notebook;
```
Påfør skjemaet på nytt.

Autorisasjonspolicy fungerer ikke

Symptom: Brukere kan få tilgang til poster de ikke skal se.

Årsak: Formuleringen i polisen er feil eller kravnavnene stemmer ikke overens.

Løsning:

Verifiser at polisen bruker korrekte kravnavn (sub, email, role):
```
policy: (claims, item) => claims.sub.eq(item.user_id)
```
Logg den dekodede JWT-en for å verifisere at kravverdiene samsvarer med koden din.

Utdaterte API-svar

Symptom: Frontend returnerer utdaterte dataformer etter skjemaendringer.

Årsak: Den genererte konfigurasjonen er bufret.

Løsning:

Stopp backend.
Slett katalogen .temp/ i rayfin/:
```
rm -rf rayfin/.temp/
```
Start tjenestene på nytt og bruk skjemaet på nytt.

CLI-problemer

Kommando ikke funnet

Symptom: Kjøring npx rayfin returnerer "kommando ikke funnet."

Årsak: CLI-en er ikke installert, eller npm er ikke i PATH-en din.

Løsning:

Sjekk Node.js og npm er installert:
```
node --version
npm --version
```
Reinstaller avhengigheter:
```
npm install
```

CLI-versjonsmismatch

Symptom: CLI-kommandoer feiler med uventede feil etter oppdatering.

Årsak: Cachet CLI-versjon er utdatert.

Løsning:

Oppdater og installer på nytt:

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

CLI-global og lokal versjonsmismatch

Symptom: CLI-kommandoer feiler med uventede feil på tvers av prosjekter.

Årsak: Global og lokal installasjon av CLI-versjonene, og de stemmer ikke overens.

Løsning: Valider lokal versjon npm list @microsoft/rayfin-cli. Dette viser versjonen i ditt nåværende prosjekts node_modules. Sjekk den globale versjonen npm list -g @microsoft/rayfin-cli. Dette viser versjonen som er installert i hele systemet. Bruk npm uninstall -g med Rayfin CLI-pakken for å fjerne den globale versjonen og bruk dine lokale versjoner.

Problemer med hemmelig administrasjon

Hemmelig kommando gir ingen varsel

Symptom:npx rayfin secret set <NAME> Går ut uten å be om en verdi.

Årsak: Standard input er ikke en interaktiv terminal, eller miljøvariabelen CI er satt til true. Kommandoen bruker en maskert interaktiv prompt.

Løsning:

Bruk ett av følgende støttede alternativer for opprettelse av ikke-interaktive hemmeligheter:

Sett én hemmelighet ved å sende verdien til kommandoen:

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

Sett flere hemmeligheter fra en miljøfil:

npx rayfin secret set --env-file .\secrets.env

Hold hemmelige verdier utenfor shell-historikken din og ikke forplikt secret.txt deg til eller .\secrets.env til kildekontroll.

Hemmelig kommando returnerer tillatelse nektet

Symptom:npx rayfin secret set eller npx rayfin secret list returnerer en tillatelsesfeil.

Årsak: Appen er ikke distribuert, eller den innloggede kontoen har ikke tilgang til mål-Fabric-arbeidsområdet.

Løsning:

Kjør npx rayfin up for å provisjonere appen.
Kjør npx rayfin login og velg en konto med tilgang til arbeidsområdet.
Prøv den hemmelige kommandoen på nytt.

For mer informasjon, se Administrer funksjonshemmeligheter.

Bygge- og emballasjeproblemer

Byggekommandoen feiler

Symptom: Utrulling av statisk hosting feiler fordi byggekommandoen ikke ga noen utdata.

Årsak: Byggefeil eller feilkonfigurert byggekommando.

Løsning:

Kjør build-kommandoen manuelt:
```
npm run build
```
Fiks eventuelle rapporterte feil.
Sjekk at utdatamappen inneholder filer.

Tom statisk mappe

Symptom: Statisk distribusjon feiler med feilen "empty folder".

Årsak: Den konfigurerte folder stien er feil.

Løsning:

Sjekk at stien folder i rayfin.yml stemmer med byggeresultatet ditt:

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

Databaseproblemer

Database schema apply feiler

Symptom: Løper npx rayfin up db apply eller npx rayfin up db apply --force mislykkes.

Årsak: Skjemaet i den eksterne databasen og skjemaet definert i appkoden er ikke synkronisert. App-koden er sannhetskilden for en Fabric-app.

Ikke endre det eksterne databaseskjemaet via Fabric-portalen, SQL Server Management Studio (SSMS), SQL Server-utvidelsen for Visual Studio Code, eller andre SQL-verktøy. Følgende endringer i kolonner i en dataenhet støttes ikke:

Omdøping av en spalte.
Endring av en kolonnes datatype.
Fjerner en søyle.

Å legge til en kolonne støttes. Å fjerne eller endre en eksisterende kolonne kan ødelegge appen og dens distribusjon til Fabric.

Løsning:

Tilbakestill alle manuelle endringer i det eksterne databaseskjemaet slik at det samsvarer med skjemaet i app-koden.
Hvis en kodeagent gjorde en ikke-støttet skjemaendring i app-koden, instruer agenten om å tilbakestille den endringen.
Kjør skjema apply-kommandoen igjen:
```
npx rayfin up db apply
```
For en omdøping av kolonnen --force kan det tillate at skjemaoppdateringen fullføres:
```
npx rayfin up db apply --force
```
Forsiktig!

--force Bruk kan føre til permanent datatap. Gå gjennom de foreslåtte operasjonene og bekreft at du aksepterer risikoen for datatap før du går videre.

Tilkobling nektet

Symptom: Dataoperasjoner feiler ved tilkoblingsfeil.

Årsak: Databasecontaineren kjører ikke, eller helsesjekker feilet.

Løsning:

Gå gjennom containerlogger:
```
docker compose logs -f
```
Start tjenestene på nytt.

Datatap etter omstart

Symptom: Data forsvinner etter at tjenester er stoppet og startet.

Årsak: Volumene ble slettet med --purge.

Løsning:

Bruk --down i stedet for --purge å bevare data.

Kjente begrensninger

For nåværende begrensninger og anbefalte løsninger, se:

count() er ikke tilgjengelig på den flytende GraphQL-klienten—bruk results.length.
Mange-til-mange-relasjoner støttes ikke—bruk en eksplisitt join-entitet.
Sesjonsobjekter er ugjennomsiktige—sjekk isAuthenticated eller user egenskaper.
Etter å ha aktivert eller deaktivert autentisering i rayfin.yml, starter backenden på nytt.

Få hjelp

Hvis problemet vedvarer:

Se gjennom dokumentasjonen Fabric Apps.
Sjekk GitHub-repositoriet for kjente problemer.
Send inn en feilrapport med detaljerte logger og reproduksjonssteg.

Tilbakemeldinger

Var denne siden nyttig?

Sist oppdatert 2026-09-29

Feilsøking av Fabric-apper

Utplasseringsproblemer

Utrulling feiler med 401- eller 403-feil

Statisk utrulling overstiger størrelsesgrensen

Statisk utrulling har ingen ekstern endepunkt

Godkjenningsproblemer

Innhenting av autentiseringstoken feiler

Økt varer ikke etter pålogging

Fabric SSO popup blokkert

Fabric-autentisering går ut på tid

Fabric SSO rapporterer om opprinnelsesmismatch

initEmbeddedAuth() Returer null

Fabric-autentisering rapporterer en tilstandsmismatch

Datamodellproblemer

Data API returnerer en intern serverfeil etter utrulling

Datatjeneste krever en dialekt

Ny enhet er ikke tilgjengelig etter utrulling

Relasjoner som ikke vises i API-et

Autorisasjonspolicy fungerer ikke

Utdaterte API-svar

CLI-problemer

Kommando ikke funnet

CLI-versjonsmismatch

CLI-global og lokal versjonsmismatch

Problemer med hemmelig administrasjon

Hemmelig kommando gir ingen varsel

Hemmelig kommando returnerer tillatelse nektet

Bygge- og emballasjeproblemer

Byggekommandoen feiler

Tom statisk mappe

Databaseproblemer

Database schema apply feiler

Tilkobling nektet

Datatap etter omstart

Kjente begrensninger

Få hjelp

Relatert innhold

Tilbakemeldinger

Flere ressurser

`initEmbeddedAuth()` Returer `null`