---
title: "Errors and troubleshooting"
description: "A symptom-to-fix index of the errors Rayfin builders hit most — deployment, schema apply, secrets, static hosting, and Fabric auth."
url: https://rayfin.ai/docs/reference/errors
markdown_url: https://rayfin.ai/docs/reference/errors.md
section: reference
product: Rayfin
sdk_version: 1.34.0
cli_version: 1.33.2
last_updated: 2026-08-23T01:28:43-07:00
source: reference/errors.mdx
---

# Errors and troubleshooting

> A symptom-to-fix index of the errors Rayfin builders hit most — deployment, schema apply, secrets, static hosting, and Fabric auth.

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 [#quick-reference]

| Symptom                                                                         | Cause                                                                            | Fix                                                                                   |
| ------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
| "Internal server error" from the data API, after a deploy that reported success | `@text()` field with no `max` produced `NVARCHAR(MAX)` on MSSQL                  | Add `@text({ max: N })` to every string field, then reapply the schema                |
| `Dialect is required when Data module is enabled` (400 at deploy time)          | `services.data.enabled: true` with no `dialect` in `rayfin.yml`                  | Set `dialect: mssql`                                                                  |
| `Failed to acquire authentication token`                                        | Not signed in, or no OS credential storage available                             | `rayfin login`; on restricted systems set `RAYFIN_ENCRYPTION_FALLBACK_ENABLED=true`   |
| `rayfin up db apply` refuses to run, warns of data loss                         | The pending change drops a column/table or alters a type                         | Review the change; re-run with `--force` only once you accept the loss                |
| A newly added entity isn't readable right after a deploy that reported success  | The schema migration step hadn't finished applying, or the client/cache is stale | Run `rayfin up status`; confirm schema apply completed before querying the new entity |
| Deployment fails with `401` or `403`                                            | Your Fabric session expired                                                      | `rayfin login`, then retry `rayfin up`                                                |
| `No remote endpoint configured` from `staticapp deploy`                         | No full deployment has happened yet                                              | Run `rayfin up` once, then use `staticapp deploy` for subsequent updates              |
| Static deploy exceeds the size limit                                            | Build output includes source maps or dev-only assets                             | Exclude dev artifacts from the production build, or move binaries to storage          |
| `rayfin secret set` exits without prompting                                     | stdin is not a TTY, or `CI=true` — the command is interactive only               | Run it from an interactive terminal; there is no CI path today                        |
| Popup blocked during Fabric sign-in                                             | `ensureSignedInWithFabric` was called outside a user-gesture handler             | Call it directly from a button's `onClick`                                            |

## Deployment and schema apply [#deployment-and-schema-apply]

### "Internal server error" after a successful deploy [#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`](/docs/reference/sdk/rayfin-core) and
[Known limitations](/docs/reference/known-limitations).

### "Dialect is required when Data module is enabled" [#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`:

```yaml title="rayfin/rayfin.yml"
services:
  data:
    enabled: true
    dialect: mssql
```

### Database apply refuses to run (potential data loss) [#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`:

```bash
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 [#a-newly-added-entity-isnt-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 [#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-and-secrets]

### Sign-in or keychain failures [#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 [#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](/docs/deploy/secrets).

### Permission denied setting or listing 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-hosting]

### Static folder not found / empty static folder [#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 [#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" [#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 [#fabric-brokered-auth]

See [`@microsoft/rayfin-auth-provider-fabric`](/docs/reference/sdk/rayfin-auth-provider-fabric)
for the full option reference these fixes refer to.

### Popup blocked [#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 [#session-not-persisting]

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

**Fix:** confirm both match your deployed backend.

### Timeout after 5 minutes [#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 [#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` [#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 [#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 [#see-also]

* [Known limitations](/docs/reference/known-limitations)
* [Deprecation warnings](/docs/reference/deprecations)
* [`@microsoft/rayfin-client`](/docs/reference/sdk/rayfin-client)