Errors and troubleshooting

This page consolidates the troubleshooting sections scattered across the Rayfin guide into one symptom → cause → fix index. Search it by the error text you're seeing, then jump to the matching heading for the full fix.

Quick reference

Deployment and schema apply

"Internal server error" after a successful deploy

Symptom: rayfin up (or rayfin up db apply) reports success, but the GraphQL or REST data API returns a generic "Internal server error" at runtime.

Cause: a @text() field with no max option produces an NVARCHAR(MAX) column on MSSQL. Rayfin's metadata provider can fail to build a GraphQL schema from that column type.

Fix: add an explicit length to every string field targeting MSSQL — @text({ max: 200 }) rather than bare @text() — then reapply the schema (npx rayfin up db apply --force if the column already exists with the wrong type). See @microsoft/rayfin-core and Known limitations.

"Dialect is required when Data module is enabled"

Symptom: rayfin up fails with a 400 error during deployment.

Cause: rayfin.yml has services.data.enabled: true but no dialect key.

Fix: add dialect: mssql (Fabric apps support MSSQL only) under services.data:

services:
  data:
    enabled: true
    dialect: mssql

Database apply refuses to run (potential data loss)

Symptom: rayfin up db apply stops and warns instead of applying the change.

Cause: the pending schema change would drop a column, drop a table, or alter a column's type — all are treated as potentially destructive.

Fix: review the listed operations. If the data loss is acceptable, re-run with --force:

npx rayfin up db apply --force

Never pass --force without reviewing what will be dropped.

A newly added entity isn't readable after a deploy that reported success

Symptom: rayfin up prints success, but querying a newly added entity immediately afterward returns nothing, or errors as if the entity doesn't exist.

Cause: the static app and runtime settings can finish deploying slightly before the database schema migration for the new entity has fully applied, or a client built before the deploy is still caching the old schema.

Fix: run npx rayfin up status and confirm the deployment is fully healthy before relying on the new entity. Refresh or rebuild the frontend client so it isn't holding a stale schema.

Deployment fails with 401 or 403

Symptom: rayfin up fails partway through with an authorization error.

Cause: your signed-in Fabric session has expired.

Fix: npx rayfin login to reauthenticate, then retry npx rayfin up.

Sign-in and secrets

Sign-in or keychain failures

Symptom: rayfin login or any command needing authentication fails with Failed to acquire authentication token or a similar credential-storage error.

Cause: you aren't signed in, or the current environment (a container, a restricted CI runner) has no OS-backed credential storage for the CLI's token cache.

Fix: run npx rayfin login — the account picker is always shown, so you can choose a different account. On systems without OS credential storage, set RAYFIN_ENCRYPTION_FALLBACK_ENABLED=true (development environments only — this stores the token cache in plaintext).

rayfin secret set refuses to prompt

Symptom: rayfin secret set <NAME> exits without asking for a value.

Cause: stdin is not a TTY, or CI=true is set. The command reads the value from a masked prompt and has no non-interactive mode.

Fix: run it from an interactive terminal. There is no supported way to set secrets from CI today. See Secrets.

Permission denied setting or listing secrets

Symptom: rayfin secret set or rayfin secret list fails with a permission error.

Cause: the signed-in account doesn't have access to the target Fabric workspace, or the project has not been deployed yet.

Fix: run npx rayfin up first so the workload exists. Then confirm you're signed in with an account that has workspace access — run npx rayfin login again, the account picker is always shown.

Static hosting

Static folder not found / empty static folder

Symptom: deployment fails saying the static output folder doesn't exist, or it exists but is empty.

Cause: the folder path in rayfin.yml (relative to root, or the project root) is wrong, or buildCommand didn't actually produce output.

Fix: verify the staticHosting.folder path, and run the build command manually (npm run build) to confirm it produces files where expected.

Deployment too large

Symptom: static deployment fails because the packaged archive exceeds the limit.

Cause: the compressed build output exceeds the 100 MB static hosting limit — often source maps or unoptimized assets.

Fix: exclude development artifacts (source maps, unminified assets) from the production build, or move large binary files to a storage service instead of bundling them as static content.

"No remote endpoint configured"

Symptom: rayfin up staticapp deploy fails, saying no remote endpoint is configured.

Cause: staticapp deploy only redeploys static content for a deployment that already exists — it can't create one.

Fix: run npx rayfin up once to provision the remote deployment, then use npx rayfin up staticapp deploy for subsequent static-only updates.

Fabric brokered auth

See @microsoft/rayfin-auth-provider-fabric for the full option reference these fixes refer to.

Popup blocked

Cause: ensureSignedInWithFabric (or initiateFabricLogin) was called outside a synchronous user-gesture handler.

Fix: call it directly from a button's onClick, not on page load or after an await.

Session not persisting

Cause: RayfinClient is misconfigured — usually the wrong baseUrl or publishableKey.

Fix: confirm both match your deployed backend.

Timeout after 5 minutes

Cause: the Fabric portal never sent the handoff code back.

Fix: confirm returnOrigin matches your app's actual origin.

Origin mismatch

Cause: fabricPortalUrl doesn't match the Fabric portal environment you're actually using (production, PPE, dev).

Fix: use the correct portal URL for your environment.

initEmbeddedAuth returns null

Cause: the SDK didn't detect embedded mode.

Fix: ensure the URL includes ?fabricEmbedded=true, or set fabricEmbedded: true explicitly in FabricAuthOptions.

State mismatch error

Cause: the response's state parameter didn't match the request — a stale response from a previous flow, or a replay attempt.

Fix: retry the sign-in flow from scratch.

See also

• Known limitations
• Deprecation warnings
• @microsoft/rayfin-client