Edit

Troubleshoot Fabric Apps

Diagnose common problems when you develop or deploy a Fabric Apps project. This article covers issues with sign-in, local services, schema changes, static hosting, and the CLI.

Deployment issues

Deployment fails with 401 or 403 error

Symptom: Running npx rayfin up returns an authentication error.

Cause: Your authentication session expired or you aren't signed in.

Solution:

Reauthenticate and retry the deployment:

npx rayfin login
npx rayfin up

Static deploy exceeds size limit

Symptom: Static content deployment fails with a size limit error.

Cause: The compressed archive exceeds 100 MB.

Solution:

Reduce build output size by:

  • Excluding source maps from production builds
  • Optimizing or removing large images and videos
  • Moving binary files to storage instead of bundling them
  • Verifying your bundler configuration excludes development artifacts

Authentication issues

Session not persisting after sign-in

Symptom: Users are signed out immediately after authentication.

Cause: The client isn't configured with the correct base URL or publishable key.

Solution:

Verify the RayfinClient configuration matches your backend:

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

Fabric SSO popup blocked

Symptom: Browser blocks the Fabric portal window during sign-in.

Cause: ensureSignedInWithFabric() wasn't called from a user-gesture handler.

Solution:

Call the function from a synchronous event handler:

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

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

Data model issues

Relationships not appearing in API

Symptom: Related entity fields aren't available when querying.

Cause: The navigation decorator is missing or the schema wasn't applied.

Solution:

  1. Verify the relationship decorators are present:

    @one(() => Notebook) notebook?: Notebook;

  2. Reapply the schema.

Authorization policy not working

Symptom: Users can access records they shouldn't see.

Cause: The policy expression is incorrect or the claim names don't match.

Solution:

  1. Verify the policy uses correct claim names (sub, email, role):

    policy: (claims, item) => claims.sub.eq(item.user_id)

  2. Log the decoded JWT to verify claim values match your code.

Stale API responses

Symptom: Frontend returns outdated data shapes after schema changes.

Cause: The generated configuration is cached.

Solution:

  1. Stop the backend.

  2. Delete the .temp/ directory in rayfin/:

    rm -rf rayfin/.temp/

  3. Restart services and reapply the schema.

CLI issues

Command not found

Symptom: Running npx rayfin returns "command not found."

Cause: The CLI isn't installed or npm isn't in your PATH.

Solution:

  1. Verify Node.js and npm are installed:

    node --version
npm --version

  2. Reinstall dependencies:

    npm install

CLI version mismatch

Symptom: CLI commands fail with unexpected errors after updating.

Cause: Cached CLI version is outdated.

Solution:

Update and reinstall:

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

CLI global and local version mismatch

Symptom: CLI commands fail with unexpected errors across projects.

Cause: Global and local installation of the CLI versions and they don't match.

Solution: Validate local version npm list @microsoft/rayfin-cli. This shows the version in your current project’s node_modules. Check global version npm list -g @microsoft/rayfin-cli. This shows the version installed system-wide. Use npm uninstall -g with Rayfin CLI package to remove global version and use your local versions.

Build and packaging issues

Build command fails

Symptom: Static hosting deployment fails because the build command produced no output.

Cause: Build errors or misconfigured build command.

Solution:

  1. Run the build command manually:

    npm run build

  2. Fix any errors reported.

  3. Verify the output folder contains files.

Empty static folder

Symptom: Static deployment fails with "empty folder" error.

Cause: The configured folder path is incorrect.

Solution:

Verify the folder path in rayfin.yml matches your build output:

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

Database issues

Database schema apply fails

Symptom: Running npx rayfin up db apply or npx rayfin up db apply --force fails.

Cause: The schema in the remote database and the schema defined in the app code are out of sync. The app code is the source of truth for a Fabric app.

Don't modify the remote database schema through the Fabric portal, SQL Server Management Studio (SSMS), the SQL Server extension for Visual Studio Code, or other SQL tools. The following changes to columns in a data entity aren't supported:

  • Renaming a column.
  • Changing a column's data type.
  • Removing a column.

Adding a column is supported. Removing or altering an existing column can break the app and its deployment to Fabric.

Solution:

  1. Revert any manual changes to the remote database schema so that it matches the schema in the app code.

  2. If a coding agent made an unsupported schema change in the app code, instruct the agent to revert that change.

  3. Run the schema apply command again:

    npx rayfin up db apply

    For a column rename, --force might allow the schema update to complete:

    npx rayfin up db apply --force

    Caution

    Using --force can cause permanent data loss. Review the proposed operations and confirm that you accept the data-loss risk before proceeding.

Connection refused

Symptom: Data operations fail with connection errors.

Cause: The database container isn't running or health checks failed.

Solution:

  1. Review container logs:

    docker compose logs -f

  2. Restart services.

Data loss after restart

Symptom: Data disappears after stopping and starting services.

Cause: Volumes were deleted with --purge.

Solution:

Use --down instead of --purge to preserve data.

Known limitations

For current limitations and recommended workarounds, see:

  • count() isn't available on the fluent GraphQL client—use results.length.
  • Many-to-many relationships aren't supported—use an explicit join entity.
  • Session objects are opaque—check isAuthenticated or user properties.
  • After enabling or disabling auth in rayfin.yml, restart the backend.

Get help

If the issue persists:

  1. Review the Fabric Apps documentation.
  2. Check the GitHub repository for known issues.
  3. File a bug report with detailed logs and reproduction steps.

Related content

  • Last updated on