---
title: "Troubleshooting overview"
description: "Start here when Fabricator is not working, then jump to the symptom that matches what you see."
url: https://spatney.github.io/rayfin-fabricator/docs/troubleshooting
markdown_url: https://spatney.github.io/rayfin-fabricator/docs/troubleshooting.md
app_version: "1.20.1"
section: troubleshooting
product: Fabricator
last_updated: 2026-10-14T22:09:52-07:00
source: troubleshooting/index.mdx
---

# Troubleshooting overview

> Start here when Fabricator is not working, then jump to the symptom that matches what you see.

Use this page when Fabricator gets stuck, a sign-in fails, a preview is blank, or a deploy does not finish. Start with the checks below, then use the symptom index.

## Ask Help first

Fabricator has a built-in assistant that reads the errors it recorded on your computer and explains what went wrong.

1. In the status bar, select **Help**, or press `Ctrl+J` (`Cmd+J` on macOS).
2. Describe the problem, such as "why did my last deploy fail?".

Help often identifies the cause faster than working through the index below, because it can see the exact error you hit. See [Ask Help](https://spatney.github.io/rayfin-fabricator/docs/troubleshooting/help).

## First steps for any problem

1. Update to the latest version. Restart Fabricator so it checks for an update, and install the update if Fabricator offers one. If you installed an old build from before auto-update existed, download and install the latest release once from [GitHub Releases](https://github.com/spatney/rayfin-fabricator/releases/latest). Future updates are in-app.
2. Restart Fabricator. This refreshes the bundled Copilot engine, PATH discovery, the preview surface, and any setup checks that depend on tools installed while the app was open.
3. Re-check setup. On the setup screen, select **Re-check** after installing Node.js, Git, Azure CLI, GitHub CLI, or after signing in.
4. Check the status bar version. The lower-right status bar shows the Fabricator app version. Include that version in reports.
5. Read the exact message. The fastest fix usually depends on the exact quoted error in the banner, modal, chat card, or setup row.

## Symptom index

| If you see this | Go here |
| --- | --- |
| Windows SmartScreen warns about the installer | [Windows says the installer is uncommon](https://spatney.github.io/rayfin-fabricator/docs/troubleshooting/install-and-updates#windows-says-the-installer-is-uncommon) |
| macOS says the app is damaged | [macOS says Fabricator is damaged and can't be opened](https://spatney.github.io/rayfin-fabricator/docs/troubleshooting/install-and-updates#macos-says-fabricator-is-damaged-and-cant-be-opened) |
| An update prompt, banner, or manual update problem | [An update won't install or keeps prompting](https://spatney.github.io/rayfin-fabricator/docs/troubleshooting/install-and-updates#an-update-wont-install-or-keeps-prompting) |
| A setup tool is missing, outdated, or failed its version check | [A tool shows as missing or failed](https://spatney.github.io/rayfin-fabricator/docs/troubleshooting/setup-and-sign-in#a-tool-shows-as-missing-or-failed) |
| GitHub Copilot sign-in fails | [GitHub Copilot sign-in doesn't work](https://spatney.github.io/rayfin-fabricator/docs/troubleshooting/setup-and-sign-in#github-copilot-sign-in-doesnt-work) |
| Chat asks you to sign in again | [Copilot asks you to sign in again](https://spatney.github.io/rayfin-fabricator/docs/troubleshooting/setup-and-sign-in#copilot-asks-you-to-sign-in-again) |
| Azure CLI is using the wrong tenant or account | [Azure CLI is signed in to the wrong account](https://spatney.github.io/rayfin-fabricator/docs/troubleshooting/setup-and-sign-in#azure-cli-is-signed-in-to-the-wrong-account) |
| Fabric sign-in does nothing or does not finish | [Fabric sign-in doesn't complete](https://spatney.github.io/rayfin-fabricator/docs/troubleshooting/setup-and-sign-in#fabric-sign-in-doesnt-complete) |
| Chat shows a Copilot error | [Chat shows a Copilot error](https://spatney.github.io/rayfin-fabricator/docs/troubleshooting/chat#chat-shows-a-copilot-error) |
| A chat turn looks stuck | [A chat turn seems stuck](https://spatney.github.io/rayfin-fabricator/docs/troubleshooting/chat#a-chat-turn-seems-stuck) |
| The chat history changed or a new Copilot session started | [The conversation disappeared or a new session started](https://spatney.github.io/rayfin-fabricator/docs/troubleshooting/chat#the-conversation-disappeared-or-a-new-session-started) |
| Copilot credits or premium requests run out | [Copilot credits run out quickly](https://spatney.github.io/rayfin-fabricator/docs/troubleshooting/chat#copilot-credits-run-out-quickly) |
| Rayfin CLI reports missing packages such as `rxjs`, `commander`, or `jsonwebtoken` | [Rayfin CLI reports missing dependencies](https://spatney.github.io/rayfin-fabricator/docs/troubleshooting/chat#rayfin-cli-reports-missing-dependencies) |
| Preview is blank, stale, or stuck opening | [The preview is blank or stuck](https://spatney.github.io/rayfin-fabricator/docs/troubleshooting/preview#the-preview-is-blank-or-stuck) |
| Every preview port is taken | [All preview ports are busy](https://spatney.github.io/rayfin-fabricator/docs/troubleshooting/preview#all-preview-ports-are-busy) |
| Preview shows an older app | [The preview shows an old version](https://spatney.github.io/rayfin-fabricator/docs/troubleshooting/preview#the-preview-shows-an-old-version) |
| The app inside the preview asks you to sign in | [The preview asks you to sign in](https://spatney.github.io/rayfin-fabricator/docs/troubleshooting/preview#the-preview-asks-you-to-sign-in) |
| The local preview says "Automatic local sign-in failed." | [The local preview says automatic sign-in failed](https://spatney.github.io/rayfin-fabricator/docs/troubleshooting/preview#the-local-preview-says-automatic-sign-in-failed) |
| Preview covers chat or other UI | [The preview covers other Fabricator controls](https://spatney.github.io/rayfin-fabricator/docs/troubleshooting/preview#the-preview-covers-other-fabricator-controls) |
| Team app local preview restarts | [A team app local preview restarts](https://spatney.github.io/rayfin-fabricator/docs/troubleshooting/preview#a-team-app-local-preview-restarts) |
| The preview says **Deploy failed** | [A deploy failed](https://spatney.github.io/rayfin-fabricator/docs/troubleshooting/deploy#a-deploy-failed) |
| Automatic redeploy no longer runs after chat | [Automatic redeploy stopped](https://spatney.github.io/rayfin-fabricator/docs/troubleshooting/deploy#automatic-redeploy-stopped) |
| Deploy keeps failing after Fabric sign-in | [Fabric authentication blocks deploy](https://spatney.github.io/rayfin-fabricator/docs/troubleshooting/deploy#fabric-authentication-blocks-deploy) |
| Semantic model reads fail | [Couldn't read the semantic model](https://spatney.github.io/rayfin-fabricator/docs/troubleshooting/deploy#couldnt-read-the-semantic-model) |
| Workspace or Fabric capacity blocks deployment | [The workspace or capacity blocks deploy](https://spatney.github.io/rayfin-fabricator/docs/troubleshooting/deploy#the-workspace-or-capacity-blocks-deploy) |
| Rayfin CLI is missing or npm reports `ETARGET` | [Rayfin CLI or npm package resolution failed](https://spatney.github.io/rayfin-fabricator/docs/troubleshooting/deploy#rayfin-cli-or-npm-package-resolution-failed) |
| Someone else cannot open the shared app | [Recipients can't open the shared app](https://spatney.github.io/rayfin-fabricator/docs/troubleshooting/deploy#recipients-cant-open-the-shared-app) |
| A team workspace step failed and its message doesn't explain why | [A team step failed and the message doesn't explain it](https://spatney.github.io/rayfin-fabricator/docs/troubleshooting/team#a-team-step-failed-and-the-message-doesnt-explain-it) |
| A team workspace setup step needs admin help | [Setup needs an administrator](https://spatney.github.io/rayfin-fabricator/docs/troubleshooting/team#setup-needs-an-administrator) |
| Team workspace setup can't create the GitHub repository in your organization | [Setup can't create the GitHub repository](https://spatney.github.io/rayfin-fabricator/docs/troubleshooting/team#setup-cant-create-the-github-repository) |
| Team workspace setup says the organization locked the repository until it's set up | [The organization locked the repository until it's set up](https://spatney.github.io/rayfin-fabricator/docs/troubleshooting/team#the-organization-locked-the-repository-until-its-set-up) |
| A team workspace pipeline's sign-in fails with AADSTS7002381 | [The pipeline's sign-in fails with AADSTS7002381](https://spatney.github.io/rayfin-fabricator/docs/troubleshooting/team#the-pipelines-sign-in-fails-with-aadsts7002381) |
| GitHub CLI is missing, signed out, or missing scopes for a team workspace | [GitHub CLI is missing, signed out, or missing scopes](https://spatney.github.io/rayfin-fabricator/docs/troubleshooting/team#github-cli-is-missing-signed-out-or-missing-scopes) |
| GitHub says an organization requires single sign-on for a team workspace | [GitHub says the organization requires single sign-on](https://spatney.github.io/rayfin-fabricator/docs/troubleshooting/team#github-says-the-organization-requires-single-sign-on) |
| A team workspace pipeline or publish run failed | [A pipeline failed](https://spatney.github.io/rayfin-fabricator/docs/troubleshooting/team#a-pipeline-failed) |
| A team workspace pipeline never starts, or setup says no runner picked it up | [No runner picks up the pipeline](https://spatney.github.io/rayfin-fabricator/docs/troubleshooting/team#no-runner-picks-up-the-pipeline) |
| Team publish is blocked by conflicts | [Publish is blocked or has conflicts](https://spatney.github.io/rayfin-fabricator/docs/troubleshooting/team#publish-is-blocked-or-has-conflicts) |
| Team previews are missing, failed, or old | [Previews are not deploying](https://spatney.github.io/rayfin-fabricator/docs/troubleshooting/team#previews-are-not-deploying) |
| A team workspace invitation is missing | [Invitations are not showing](https://spatney.github.io/rayfin-fabricator/docs/troubleshooting/team#invitations-are-not-showing) |
| Team workspace pipeline health says Repair is needed | [Repair is needed after updates](https://spatney.github.io/rayfin-fabricator/docs/troubleshooting/team#repair-is-needed-after-updates) |
| Any team workspace problem | [Team workspace problems](https://spatney.github.io/rayfin-fabricator/docs/troubleshooting/team) |

## Get help

If the fix for your symptom does not work, collect diagnostics and open a report:

1. In the status bar, select **Help**.
2. Describe the problem, or ask Help to report it for you.
3. Select **Report this on GitHub**, then drag the diagnostics file that Fabricator created onto the issue.

See [Report a problem](https://spatney.github.io/rayfin-fabricator/docs/troubleshooting/report-a-problem) for what Fabricator includes and what to remove before posting publicly.