From c827b9bb8dccf6cb66cf6a35addcdfd9c649cac3 Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Tue, 18 Aug 2026 15:38:12 +0000 Subject: [PATCH] docs: correct the Smart App Control guidance The troubleshooting section told users to run 'Unblock-File -Path ... -Recurse', which is not valid PowerShell (the cmdlet has no -Recurse parameter) and would not help even in its correct form: Smart App Control gates on the signature and on cloud reputation, not on Mark-of-the-Web. It also said Evaluation mode triggers blocks, and advised turning Smart App Control off temporarily and back on again. Evaluation never blocks, and Windows cannot re-enable Smart App Control without a reset or reinstall. Say instead that the Windows builds are unsigned, that Windows has no per-app exception, and what the two real options are. Split the section in three, since it served two unrelated failures and the 'extract to a new folder' fix only applies to one of them: a Smart App Control block, an incomplete in-app upgrade, and installing into a synced folder. Keep the original anchor on the Smart App Control section so links in released builds still land somewhere useful. Refs #1967, #1873, #1876 Co-authored-by: rmcrackan --- docs/advanced/troubleshoot.md | 59 +++++++++++++++++++++++++---------- docs/getting-started.md | 5 ++- 2 files changed, 46 insertions(+), 18 deletions(-) diff --git a/docs/advanced/troubleshoot.md b/docs/advanced/troubleshoot.md index b6fd5061..681deefa 100644 --- a/docs/advanced/troubleshoot.md +++ b/docs/advanced/troubleshoot.md @@ -78,38 +78,63 @@ Platform-specific steps: [Windows](#hangover-windows) ยท [macOS](#hangover-macos ## Windows -### Smart App Control and in-app upgrades {#windows-smart-app-control-and-in-app-upgrades} +### Smart App Control blocks Libation {#windows-smart-app-control-and-in-app-upgrades} -After accepting an in-app update, Libation may fail to restart with an error like: +Libation fails to start, or fails part way through, with an error like: `An Application Control policy has blocked this file. (0x800711C7)` -Windows **Smart App Control** (and similar Application Control policies on recent Windows 11 builds) can block DLLs that were just written when the in-app upgrader overlays a new release onto your existing install folder. The blocked path is usually under your **Libation install folder** (where `Libation.exe` lives), not your user data folder (`%UserProfile%\Libation`). +**Cause:** Libation's Windows builds are not code-signed. Smart App Control runs code only when Microsoft's cloud reputation service recognises it or when it carries a signature from a trusted certificate authority, so it blocks Libation's files. The blocked path is a file in your **Libation install folder** (where `Libation.exe` lives), not your user data folder (`%UserProfile%\Libation`), and it is often a third-party library rather than a Libation one. + +An in-app upgrade frequently triggers the first block, because the upgrader writes fresh files that have no reputation yet. **Symptoms** -- Fatal crash immediately after an in-app upgrade (Chardonnay / Avalonia). +- Fatal crash on start, often right after an in-app upgrade (Chardonnay / Avalonia). - Classic may start but library import or database access fails with the same `0x800711C7` message on a `.dll` in the install folder. - Windows Security may also warn about an unsigned library. -**Fix (recommended)** +**Check which mode Smart App Control is in** + +Open **Settings** -> **Privacy & Security** -> **Windows Security** -> **App & browser control** -> **Smart App Control settings**. + +| Mode | Blocks Libation? | +|------|------------------| +| Off | No | +| Evaluation | No. This mode observes only; it never blocks anything | +| On | Yes | + +Windows can move itself from Evaluation to On on its own, which is why Libation can work one day and be blocked the next without you changing anything. + +**If it is On** + +Windows has no way to allow a single app through Smart App Control. Microsoft's guidance is to turn it off or to ask the developer to sign the app. Reinstalling, extracting to a different folder, and unblocking files all leave the signature missing, so none of them help. + +That leaves two real options: turn Smart App Control off, or run Libation on a machine that does not have it on. + +> [!WARNING] Turning Smart App Control off cannot be undone +> Windows will not turn Smart App Control back on without a reset or reinstall. An earlier version of this page suggested disabling it temporarily and re-enabling it afterwards. That is not possible; ignore that advice if you saw it. + +**If it is already Off** + +Then the block comes from a different Application Control or Device Guard policy, normally one set by whoever manages the PC. Ask them to allow Libation. + +Reports: [#1873](https://github.com/rmcrackan/Libation/issues/1873), [#1876](https://github.com/rmcrackan/Libation/issues/1876), [#1967](https://github.com/rmcrackan/Libation/issues/1967). + +### Recover from an incomplete in-app upgrade {#windows-incomplete-in-app-upgrade} + +If Libation reports that an in-app upgrade did not replace every install file, or fails to load a component after an upgrade, the install folder holds a mix of old and new files. This is a different problem from a Smart App Control block, and reinstalling does fix it. 1. Quit Libation completely. -2. Download the latest [release zip](https://github.com/rmcrackan/Libation/releases/latest) from GitHub. -3. Extract to a **new folder** (for example `C:\Apps\Libation`). Do **not** copy new files on top of the old install folder. -4. Run `Libation.exe` from the new folder. Your library database, accounts, and settings in `%UserProfile%\Libation` (or the path in `appsettings.json` -> `LibationFiles`) are separate and should still work. +2. Download the latest [release](https://github.com/rmcrackan/Libation/releases/latest) from GitHub. The `*-setup.exe` installer is the easiest option. +3. If you use the zip instead, extract it to a **new folder** (for example `C:\Apps\Libation`). Do **not** copy new files on top of the old install folder. +4. Run Libation from the new install. Your library database, accounts, and settings in `%UserProfile%\Libation` (or the path in `appsettings.json` -> `LibationFiles`) are separate and should still work. -**If Windows still blocks the new install** +### Libation installed in OneDrive or another synced folder {#windows-cloud-sync-install} -1. Open **Windows Security** -> **App & browser control** and review **Smart App Control** (Evaluation or On modes are the usual trigger). -2. In PowerShell, unblock the install folder (adjust the path): +Install Libation to a normal local path, not inside OneDrive, Dropbox, or a similar synced folder. The `*-setup.exe` installer does this for you by installing under `%LocalAppData%`. - ```powershell - Unblock-File -Path 'C:\Apps\Libation\*' -Recurse - ``` - -3. Avoid running Libation from cloud-sync folders (OneDrive, etc.) if you can; use a normal local path for the install folder. -4. If needed, turn Smart App Control off temporarily, install from the [standalone setup](https://github.com/rmcrackan/Libation/releases/latest) (override Windows' "potentially unsafe" warning if prompted), and run Libation once. Some users report that Libation keeps working after turning Smart App Control back on. [#1876](https://github.com/rmcrackan/Libation/issues/1876), [#1873](https://github.com/rmcrackan/Libation/issues/1873). +Sync clients replace files with placeholders, restore old copies, and leave conflict copies behind. In an install folder that breaks in-app upgrades and, when it happens to the search index, corrupts it. ### Hangover (Windows) diff --git a/docs/getting-started.md b/docs/getting-started.md index 43405df8..809dcb1c 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -25,12 +25,15 @@ Nearly 100% of the difference is look and feel -- it's a matter of preference. Do not install to `Program Files`. Read-only install folders break configuration and in-app updates. -**Portable (advanced):** download the `.zip` instead, extract to a folder you can write to, and run `Libation.exe` from that folder. Zips are also what the in-app updater uses when you choose to upgrade from inside Libation. +**Portable (advanced):** download the `.zip` instead, extract to a folder you can write to, and run `Libation.exe` from that folder. Zips are also what the in-app updater uses when you choose to upgrade from inside Libation. Extract to a normal local path, not inside OneDrive or another synced folder - see [Troubleshooting](/docs/advanced/troubleshoot#windows-cloud-sync-install). Chardonnay is available for x64 and arm64. Classic is x64 only. Requires 64-bit Windows 10 or later. Older versions of Windows are not supported. +> [!WARNING] Smart App Control blocks Libation +> Libation's Windows builds are not code-signed, so Windows may warn that they are unsafe. If **Smart App Control** is turned on it blocks Libation outright, and Windows offers no way to allow a single app through. See [Troubleshooting](/docs/advanced/troubleshoot#windows-smart-app-control-and-in-app-upgrades). + - [Linux](./installation/linux.md) (if you use **Snap**, read the [Snap](./installation/linux.md#snap) section after each refresh so `appsettings.json` and `LibationFiles` stay on the same revision) - [MacOS](./installation/mac.md)