Errors and troubleshooting

This page is a symptom → cause → fix index across every area of Rayfin. Search it by the error text you're seeing, then jump to the matching heading — or to the area's own troubleshooting section — 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, pass --encryption-fallback-enabled (or set RAYFIN_ENCRYPTION_FALLBACK_ENABLED=true) — development environments only, because the token cache is then stored 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, so the masked prompt can't run.

Fix: pipe the value in with --stdin, or set several secrets at once from a dotenv file with --env-file:

printf '%s' "$API_KEY" | npx rayfin secret set API_KEY --stdin
npx rayfin secret set --env-file .env.secrets

See Secrets for CI usage and rotation.

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, and serve large media from outside the static bundle.

Static hosting posture is missing

Symptom: rayfin up stops with Static hosting is enabled but services.staticHosting.assetAccess is not set in rayfin.yml, or the deployed app reports that the access posture has not been recorded.

Cause: since Rayfin 1.35.1, a static-hosted app must declare who can load it.

Fix: set the posture explicitly, then redeploy with npx rayfin up:

services:
  staticHosting:
    enabled: true
    assetAccess: protected # or: public

protected requires Fabric sign-in before the app loads; public serves anyone with the link. A non-interactive rayfin up writes protected for you when the value is missing. See Hosting and Deployment troubleshooting for the related posture errors.

"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.

Functions

See Run functions locally and Deploying functions for the full lists.

"authentication is required when Functions are enabled"

Symptom: rayfin up or rayfin dev fails with Invalid services.functions.auth: authentication is required when Functions are enabled.

Cause: Rayfin 1.36 requires enabled Functions to declare application authentication.

Fix: add the auth block:

services:
  functions:
    enabled: true
    auth:
      type: application

"No value available for secret"

Symptom: a function throws No value available for secret 'API_KEY'. Ensure it is declared in rayfin.yml and set with 'rayfin secret set'.

Cause: the function reads ctx.Secrets.API_KEY, but the secret is not declared, or it has no value in the deployed item.

Fix: run npx rayfin secret set API_KEY --describe="What the key is for", then redeploy. See Secrets in functions.

HTTP 502 from a function call during development

Symptom: while npm run dev is running, client.functions.<name>.invoke() fails with HTTP 502.

Cause: the Vite dev server proxies function calls to the local Functions host, and that host is not running. The proxy never falls back to the deployed function.

Fix: restart npm run dev, or run npx rayfin dev functions apply and read its output.

Connectors

See Connectors and the rayfin connector reference for per-command errors.

SELECTION_REQUIRED

Cause: a query chain with .where(), .orderBy(), or .first() has no explicit selection, or the entity is missing from connectorConfig.entities.

Fix: add .select([...]) to the chain, and list the entity in connectorConfig.entities.

FEATURE_NOT_ENABLED or 404 from /connector-invoke/<name>

Cause: connector invocation is disabled for the Fabric workspace. The message comes from the service, not from your app.

Fix: ask your Fabric administrator to enable it for the workspace. Changing the app does not help.

Connector type "kusto" is not available in this release.

Cause: Rayfin 1.36 holds new Kusto (Eventhouse) connectors back.

Fix: existing Kusto connectors keep working; see KQL databases.

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