mirror/Libation
1
0
Fork 0
mirror of https://github.com/rmcrackan/Libation.git synced 2026-05-08 23:54:10 -04:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #1759 from rmcrackan/rmcrackan/1694-mac-docs

Browse Source 
Improve mac troubleshooting docs per discoveries in #1694
This commit is contained in:
rmcrackan
2026-04-23 11:13:42 -04:00
committed by GitHub
parent acfde519f5 01487690d4
commit 14bd9d9deb
4 changed files with 40 additions and 5 deletions
Download Patch File Download Diff File Expand all files Collapse all files

5
.editorconfig Normal file
View File

@@ -0,0 +1,5 @@
# https://editorconfig.org
root = true
[*.md]
charset = utf-8

2
.github/ISSUE_TEMPLATE/bug_report.md vendored
View File

@@ -40,4 +40,6 @@ Attach your Libation log file here. If your user folder contains the file "Libat
|macOS|`~/Library/Application Support/Libation`|
|Linux|`~/.local/share/Libation`|
**macOS:** If that folder does not exist because Libation never starts, try launching from Terminal and say whether it works: `/Applications/Libation.app/Contents/MacOS/Libation` (see [Troubleshooting for macOS](https://github.com/rmcrackan/Libation/blob/main/docs/advanced/troubleshoot.md#macos)).
Alternative, you may open the log file folder from within Libation. Open Libation's settings, and on the first tab in Settings you can click the button 'Open log folder'.

30
docs/advanced/troubleshoot.md
View File

@@ -7,22 +7,42 @@ It is located alongside the Libation app (though not included in the docker cont
### Windows
Hangover.exe is located in the folder containing Libation.exe. Double-click it to rune it.
Hangover.exe is located in the folder containing Libation.exe. Double-click it to run it.
### macOS
Hangover is located inside the app bundle. Either:
1. From a terminal, run this command: `open -a Libation.app --args hangover`
**Hangover** is located inside the app bundle. Either:
1. From a terminal, run this command: `open /Applications/Libation.app --args hangover`
2. Run it from within the app bundle.
1. In finder, right-click the Libation app bundle and "Show Package Contents"
2. Open folders "Contents" > "MacOS"
3. Find the file named "Hangover" and double-click it to run it.
3. Find the file named "Hangover" and double-click it to run it.
**App won't start** (for example the Dock icon appears and bounces but no window opens, or **`~/Library/Application Support/Libation` is never created**): macOS may be blocking or mishandling launch of the app bundle. That can happen with strict security settings, quarantine flags on the download, or **unsupported macOS setups** (for example hardware past Apple's support window with tools such as OpenCore Legacy Patcher). Symptoms can include double-clicking Libation doing nothing useful, Activity Monitor showing almost no CPU use, no logs yet, and **`open /Applications/Libation.app --args hangover`** failing with error **-128** (`_LSOpenURLsWithCompletionHandler`). Libation is intended for **Apple-supported macOS releases** in [Install on MacOS](/docs/installation/mac); unofficial upgrades are **not supported**, and the steps below are community-tested workarounds.
Try the following in order:
1. **Clear extended attributes (including quarantine)** on the installed app, then try opening Libation again from Applications:
```bash
xattr -cr /Applications/Libation.app
```
2. **Run the main executable from Terminal** (same idea as [Running LibationCli](/docs/installation/mac#running-libationcli), but for the GUI). This bypasses some Launch Services paths and has resolved "won't start" reports where `open` failed (for example with error **-128**):
```bash
/Applications/Libation.app/Contents/MacOS/Libation
```
To capture any output to a file (it may be empty):
```bash
/Applications/Libation.app/Contents/MacOS/Libation > ~/Desktop/libation_debug.log 2>&1
```
3. If you still need Hangover and **`open /Applications/Libation.app --args hangover` fails**, run **Hangover** from the bundle using Finder (see option 2 under **Hangover** above).
4. Confirm you installed the **correct architecture** ([Install on MacOS](/docs/installation/mac)): **arm64** for Apple Silicon, **x64** for Intel.
5. **Crash logs**: open **Console** (Applications, then Utilities), or check **~/Library/Logs/DiagnosticReports** for recent **Libation** crash reports if the process exits abruptly.
### Linux (either the .deb or .rpm installers)
The installer creates shortcuts for `libation`, `libationcli`, and `hangover`. From a terminal, run `hangover`.
### Linux: in-app Audible login or “add account” fails
### Linux: in-app Audible login or "add account" fails
Embedded sign-in uses WebKit2GTK (`libwebkit2gtk`). If that native stack is missing, install the packages for your distro or use 'external browser' sign-in in Libation's import/library settings. Details: [Install on Linux](/docs/installation/linux) (section: Runtime dependencies (Audible sign-in)).

8
docs/installation/mac.md
View File

@@ -25,6 +25,14 @@ Libation comes with a recovery app called Hangover. You can start it by running
open /Applications/Libation.app --args hangover
```
## Troubleshooting
See the [macOS section of Troubleshooting](/docs/advanced/troubleshoot#macos) especially when:
* Libation does not start
* Hangover does not help
* You hit Gatekeeper or quarantine issues
## Running LibationCli
Libation comes with a command-line interface. Unfortunately, due to the way apps are sandboxed on mac, its use is somewhat limited. To open a new sandboxed terminal in LibationCli's directory, run the following command: