Troubleshooting

When something goes wrong, Fabric Desktop by KratosBI says what happened in a sentence and keeps the technical text in Activity (the bell) under Details. Find the sentence you saw below. If it isn't here, use Report a problem in the account menu: it collects the build and recent errors for you, without your data.

Starting the app#

What you see	What it means	What to do
"Windows protected your PC"	SmartScreen doesn't know the exe yet because it isn't code-signed.	More info > Run anyway.
A blank white window	The WebView2 runtime is missing or broken.	Install the WebView2 Runtime and start again.
Windows Smart App Control blocked it or An App Control policy on this PC blocked it	Windows refused the engine's unsigned Python packages. Reinstalling won't help.	See Install: If Windows blocks the engine.
"Could not check for a newer build"	GitHub didn't answer, or its limit of 60 checks an hour from your network was reached.	Nothing. The app runs the build you have and checks again next start.
"The update didn't take"	The new exe couldn't replace the old one, usually because another copy was still running or antivirus held the file.	Close every Fabric Desktop by KratosBI window, then download `fabric-desktop.exe` again from the Releases page.
"The engine could not be installed"	The engine download or unpack failed. The log is under the message.	Check the internet connection and disk space, then Retry.
"The engine download doesn't match the checksum its release gives" or "...is a different build from the one its release names"	The download didn't match what the release says it should be, so it wasn't installed. Usually a new build was being published at that moment; rarely, a proxy changed the file.	Wait a few minutes, then Retry. If it keeps happening, report it with the log under the message.
"Could not read build ...'s checksum from its release" during an update	The app couldn't read the release's `version.json`, so it couldn't check the new exe and didn't install it.	Check the internet connection, then try the update again.
"The local engine stopped while doing this"	The Python engine crashed. It restarts on your next action.	Try again. If it keeps happening, report it; `%LOCALAPPDATA%\FabricDesktop\sidecar.log` has the reason.
"The local engine stopped answering, so the app restarted it"	A quick request (opening a notebook, reading variables, checking a running cell) had no answer for 60 seconds, so the app ended the engine instead of freezing. Notebook variables are gone.	Run the notebook's cells again. If it keeps happening, report it with the request named in the details and `%LOCALAPPDATA%\FabricDesktop\sidecar.log`.

Signing in#

What you see	What it means	What to do
"Your organization's sign-in rules (Conditional Access) blocked this sign-in"	A Conditional Access policy: often "require a managed device", or one that blocks Microsoft's developer tools such as Fabric CLI.	Use a PC your organization manages, or ask IT to allow the Fabric CLI app for you (permissions.md).
"Your organization hasn't allowed this sign-in yet"	Your organization uses its own app registration and hasn't approved it, and users can't consent themselves.	Copy the link in Settings > Account > Admin approval and send it to a Microsoft Entra admin.
"Your sign-in doesn't carry the permission this feature needs"	Microsoft's sign-in doesn't cover that feature (Key Vault secrets, or finding someone in the directory), or your organization's own app lacks the permission.	Details names it. permissions.md says what IT can change.
"Could not grant admin consent ... does not have a subscription (or service principal)" (admin, in Entra)	The tenant has no service principal for one of the APIs.	Create it with `az ad sp create --id <id>` (permissions.md).
"Your organization needs an extra sign-in step (multi-factor authentication)"	Entra asked for MFA (codes AADSTS50076, 50079, 50074 or 50072).	Sign in again and finish the step in the Microsoft window. If no window offers it, set up MFA at https://aka.ms/mfasetup first.
"That account doesn't belong to your organization's Fabric tenant"	You signed in with a personal or guest account the tenant doesn't know (AADSTS50020, 50034 or 90072).	Sign in with your work account. Settings > Account > Sign out first if Windows picked the wrong one.
"Microsoft sign-in didn't finish"	Entra stopped the sign-in with a code the app doesn't explain yet.	Sign in again. If it repeats, send IT the code from Details (it starts with `AADSTS`).
Closing the sign-in window	You cancelled.	Nothing is shown and nothing changes; sign in when you're ready.
"Your sign-in expired"	The saved token couldn't be renewed.	Sign in again. If it repeats, close the app, delete `%LOCALAPPDATA%\FabricDesktop\msal_cache.bin`, and start again.
A new permission still isn't working after consent	Your saved token was issued before the permission was added.	Close the app, delete `msal_cache.bin`, start again and sign in. Or wait up to an hour.
The Fabric page or Monitoring hub asks you to sign in every time	The saved Fabric sign-in couldn't be restored.	Sign in once more. If it keeps asking, delete `%LOCALAPPDATA%\FabricDesktop\fabric-view-signin.bin` and sign in again.

Workspaces, lakehouses and data#

What you see	What it means	What to do
Workspaces is empty	Your account has no role on any workspace.	Ask a workspace admin to add you.
"You don't have permission for that in this workspace"	You need a higher workspace role for that action.	Contributor or above to write; Admin to change access.
"Skipped N workspaces" on OneLake	Those workspaces couldn't be read with your access.	Usually fine. Ask for a role if you need them.
Every read or write in OneLake is refused, but Fabric works in the browser	The tenant setting Users can access data stored in OneLake with apps external to Fabric is off for you.	A Fabric admin turns it on (azure-setup.md).
"The workspace's Fabric capacity is paused or full"	Creating items, or anything that runs in Fabric, needs an active capacity.	Resume or scale the capacity, or wait. Work on your PC isn't affected.
"Fabric doesn't accept that name" when creating a lakehouse	Lakehouse names can use only letters, numbers and underscores, and must start with a letter, so `TPC-H_Benchmark` is refused.	Use a name like `TPC_H_Benchmark`. The New lakehouse box now says this before anything is sent.
"... isn't in ... yet. Run the TPC-H data notebook"	TPC-H benchmark reads the tables TPC-H data writes, and that notebook hasn't run on the attached lakehouse.	Attach the same lakehouse to TPC-H data, run it once, then run TPC-H benchmark again.
"Fabric is busy and asked the app to slow down"	Fabric throttled the requests.	Wait a minute and retry.
A new table shows under Unidentified in Fabric	Fabric hasn't picked up a table written from outside yet.	Refresh the lakehouse in Fabric. See also xray-fixes.md.
Endorsed items is greyed out	Reading endorsement needs an admin-only permission, which Fabric Desktop by KratosBI doesn't ask for.	Nothing to fix: the Fabric catalog embedded on the same page shows endorsement.
Couldn't list capacities when creating a workspace	Your sign-in lacks `Capacity.Read.All` (your organization's own app registration doesn't have it).	Create the workspace in Fabric, or an admin adds it (permissions.md).

Notebooks and SQL#

What you see	What it means	What to do
"This notebook only runs in Fabric"	A cell uses something the PC doesn't have: RDDs, UDFs, streaming, Scala or R, or SQL MERGE/UPDATE/DELETE. The note names the cell.	Rewrite that cell, or set Runs on to Fabric.
"This notebook can't run in Fabric yet"	No lakehouse is attached, or a cell reads a path on your PC like `C:\data`.	Attach a lakehouse, or read the file from the lakehouse's `Files`.
A `%pip install` line is skipped	The engine's packages are fixed.	Use the packages the engine has (Polars, DuckDB, pandas, pyarrow, deltalake and more), or run the notebook in Fabric.
Writing a table says it is managed by the framework	The table belongs to a metadata entity.	Change the entity instead, or write to a `scratch_` table.
Cancel doesn't stop a cell	The code is stuck inside a library call that can't be interrupted.	Restart kernel. Variables are cleared. With Run notebooks in their own process on (Settings), this ends only the notebook's process; otherwise it restarts the app's engine.
A cell ends with "The notebook's Python process stopped (exit code ...)"	With notebooks in their own process, the cell's code (or a library it called) ended the process.	Run the cell again: it starts a fresh process, so run earlier cells first.
A SQL query fails on a Spark-only feature	Not every Spark SQL function has a DuckDB match.	The error names the part it couldn't run. Rewrite that part, or run the query in Fabric.

Metadata#

What you see	What it means	What to do
"N problems to fix" banner	The project doesn't pass the save gate. Runs and promote stay blocked.	Fix each listed problem in its entity file. An approved exception in `exceptions.toml` is the escape hatch.
A run Needs a decision	The table's logic changed and it loads incrementally.	Choose Apply to new rows only or Rebuild it and everything downstream (guide).
"check ... failed on N rows, so nothing was written"	A check with `on_fail = "stop"` failed.	Open the run's details, fix the data or the rule, or change `on_fail` to `quarantine`.
"no files match ..."	The source pattern found no files in the layer's lakehouse `Files`.	Check the path and that files were delivered. In Dev on the PC, files go in `.local`.
"... has not been loaded in yet"	The table this one reads hasn't been run in this environment.	Run upstream first, or Run all, which runs in layer order.
Promote says "things to do first"	The promote gate isn't met.	Each line says what: a failing test, a table whose last run isn't green on this version, or a save gate problem.
"Assign a workspace before Test can run"	The environment has no workspace.	Environments and promote > Assign workspace.
A Fabric run "stopped before it saved any results"	The runner notebook failed in Fabric.	Open it from Monitor to see the notebook's output in Fabric.
Fabric schedule or Run in Fabric fails with 403	You aren't Contributor on the workspace, or your organization's own app registration lacks `Item.Execute.All`.	Ask for Contributor, or an admin adds the permission and you sign in again (permissions.md).
A scheduled run on this PC didn't happen	The PC was off, asleep or nobody was signed in to Windows; or the app was signed out.	Use a Fabric schedule for runs that must happen. Monitor > Schedules shows each run and why it was skipped.

Source control#

What you see	What it means	What to do
"Git isn't installed on this PC"	The app uses your own Git and couldn't find it.	Install Git for Windows (it includes Git Credential Manager), then reopen Source control.
"Git couldn't sign in"	Git Credential Manager has no sign-in for that server, or it was cancelled. The app never asks for a password itself.	Run `git fetch` once in a terminal in that folder to sign in, or check Repository settings > Signing in. For Azure DevOps, check that your account can read the project.
"You don't have permission"	You're signed in, but that account can't read or push to the repository or branch.	Ask the repository owner for access, or check that Git Credential Manager is using the right account.
"The SSH key was refused" or "The server's SSH key isn't known yet"	Your key isn't loaded in the SSH agent, or this is the first connection to the server. The app doesn't answer SSH prompts.	Run `ssh-add` for your key, then `ssh -T git@github.com` (or your server) once in a terminal and accept the host key.
"The remote has commits you don't have"	Someone pushed first.	Pull, then push again.
"Your branch and the remote have both moved on"	A fast-forward pull isn't possible.	Pull > Merge, or keep working and merge later.
"This branch is protected"	The server refuses direct pushes to it.	Push to a new branch and Create pull request.
"Git needs your name and email"	No identity is set for commits.	Repository settings > Your name on commits.
"Commit blocked: this looks like a secret"	The secret check found a key, token or password in a staged file.	Move the value to Key Vault or a variable library, or It isn't a secret, commit if it's a false alarm. See Secrets are checked.
"Another Git operation is still running"	A fetch, pull or push is still going in that repository.	Wait for it, or Cancel it in the band at the top of the page.

Still stuck#

Open the bell and expand Details on the error.
Report a problem (account menu). It copies the build, channel, page and recent errors, and opens your organization's support contact or a new GitHub issue. Before anything is copied it takes out tokens, keys, passwords (including one in a web address such as https://user:token@host), Teams webhook addresses, email addresses, your Windows user name in file paths, and tenant, workspace and item ids. Table and workspace names in an error stay, so read it before you send it.
If you were asked for logs, make a support bundle instead of sending the raw log. In a terminal where the engine is installed, run fabric-desktop support-bundle --out %USERPROFILE%\Desktop. It saves a zip with the app and engine versions, where each setting comes from, and the last 2,000 lines of the engine's log, with the same details taken out. CONTENTS.txt in the zip lists what's inside. On an agent server, add --agent-home <its home folder> to include the agent's log.