docs/advanced/troubleshoot.md
Symptoms: Libation or LibationCli refuses to start with Invalid Settings.json (GUI) or Invalid configuration (CLI). The message names the setting, the bad value, and (for enums) the allowed values.
Common causes:
TokenStorageMethod mistyped (canonical values are Encrypted and Plaintext - casing variants like PlainText are accepted, but unknown spellings are not)Serilog.WriteTo missing, empty, or malformed (not an array of objects with Name). Hand-edited custom sink names are allowed; legacy ZipFile is migrated to File automatically, and a File sink missing the size-rolling arguments has them filled inSerilog.MinimumLevel set to a value that is not a Serilog levelFix: Edit Settings.json in your Libation Files directory to a valid value and restart. Do not delete the whole file unless it is corrupt JSON.
NTFS filesystems (Windows, and NTFS-formatted external drives on Linux or Mac) do not allow colons (:) in filenames. Libation chooses filename replacement rules from the OS it is running on, not from the filesystem where books are saved. On Linux or in Docker, that often means colons are left in names even when LIBATION_BOOKS_DIR points at an NTFS volume, which can produce invalid paths, failed moves, or mangled folder names.
Fix: Add or edit ReplacementCharacters in Settings.json on your config volume (or Libation files directory) so colons are replaced before download. The HiFi_NTFS example includes a colon replacement. See Command Line Interface - Set custom replacement characters.
Symptoms: Downloads that were working start failing one after another, and the log fills with System.IO.IOException: Input/output error naming paths under your Books location. On a removable drive the folder often still appears to be there, because the mount point answers even though nothing on it can be read.
Cause: The drive itself, not Libation. A USB drive that has been pulled, is failing, or has gone to sleep reports an I/O error for every read. Libation now reports the folder as unreadable and carries on. Older versions closed with a fatal error instead, and kept closing on launch until the Books location was changed (#1984).
What to try:
chkdsk on Windows, fsck on Linux).Books in Settings.json back to a folder on your internal disk.Books already downloaded to the drive are unaffected; Libation finds them again once the drive is readable.
There are two possible causes of this error.
DELETE by one of two methods.
PRAGMA journal_mode=DELETEsqlite3 "path/to/libation/files/LibationContext.db" "PRAGMA journal_mode=DELETE;"Audible returned an HTML page instead of JSON. Common causes: transient outage, expired login, VPN/proxy, or rate limiting. What to try:
Work down this list. The first two account for most reports, and neither leaves any trace in the log.
"ImportEpisodes":true,"ImportPlusTitles":true.Library scan tally. {"LibraryItems":434,"EpisodesFetched":1724,"OrphanedEpisodesDropped":15,
"ImportEpisodes":true,"EpisodeItemsExcluded":0,
"ImportPlusTitles":true,"PlusTitlesExcluded":0,"ItemsToImport":2143}
PlusTitlesExcluded or EpisodeItemsExcluded above zero means a setting from step 3 is dropping titles.
An Audible did not return ... catalog products warning means Audible sent an incomplete response even after
Libation asked again. podcast episodes were not imported because their series parent was missing names each
episode that was dropped.
If the title is still missing after all of that, open a bug report with the log and say which title it is - the ASIN if you have it, from the book's Audible URL.
Symptoms: The Windows (or other desktop) app shows your full library and new titles, but Docker / Linux finds no new books after you copy AccountsSettings.json from that machine. Container or Libation.log output includes Failed to decrypt ExistingAccessToken.
Cause: Libation can encrypt auth tokens in AccountsSettings.json using a key stored in the OS secret store (on Windows: DPAPI). That key does not travel when you copy only the JSON file into Docker, so the container cannot decrypt the tokens and the library scan fails.
Quick check: Open AccountsSettings.json on the Docker config volume. If you see "IsEncrypted": true near ExistingAccessToken, RefreshToken, or related fields, that is the problem.
Preferred fix (keep encryption): On the desktop machine, export the master key:
LibationCli export-master-key libation-master.keyCopy libation-master.key into the Docker config folder next to AccountsSettings.json and restart. Or set LIBATION_MASTER_KEY_FILE / LIBATION_MASTER_KEY (see Docker environment variables). Treat the key file like a password.
Fix with plaintext tokens: In the desktop app, open Settings -> Important, uncheck Store authentication tokens encrypted, and when prompted choose Yes to decrypt and re-save existing tokens as plaintext. Copy the updated AccountsSettings.json (and Settings.json) into the Docker config folder and restart the container.
Fix without copying Windows accounts: Create or refresh credentials inside Docker with login-external or import-account. See Docker - Adding Audible accounts without the GUI.
Also listed under Docker Troubleshooting and the FAQ.
Symptoms: Docker or headless logs show an Error like Failed to encrypt identity field ExistingAccessToken (locale us). Saving as plaintext so the app can continue. (often several fields in a row). The container keeps scanning and liberating; it does not exit for this alone.
Cause: Token storage is set to encrypted, but no usable protector is available in that environment (typical in Docker without libation-master.key / LIBATION_MASTER_KEY* and without an OS secret store). On the next write - commonly after an access-token refresh - Libation tries to encrypt, fails, and falls back to plaintext so the app is not blocked.
What to do: Nothing is required for the app to keep working. To store tokens encrypted at rest instead, supply a master key (export from desktop, or see Docker encrypted-tokens warning). To avoid the encrypt attempts and the Error noise, set token storage to plaintext in Settings -> Important (or TokenStorageMethod in Settings.json) and convert existing tokens when prompted.
Not the same as decrypt failure: If the log says Failed to decrypt ExistingAccessToken, tokens are already ciphertext you cannot unlock - the plaintext-save fallback does not help. Use the decrypt troubleshooting steps.
If your Audible account predates Amazon and login fails when you use an email or a normal region, choose a pre-amazon locale and enter your old username in the Audible email/login field. See the FAQ.
When troubleshooting, you may be asked to run 'Hangover'. Hangover is a debugging app to help diagnose and solve some problems with Libation. It is located alongside the Libation app (though not included in the docker container).
Platform-specific steps: Windows · macOS · Linux
Libation fails to start, or fails part way through, with an error like:
An Application Control policy has blocked this file. (0x800711C7)
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
0x800711C7 message on a .dll in the install folder.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 three options: wait for signed builds, run Libation on a machine that does not have Smart App Control on, or turn Smart App Control off.
Code signing is in progress. Libation has applied to the SignPath Foundation, which signs open source projects for free. Signed builds run under Smart App Control with nothing to change on your side. The application has to be approved first, so there is no date for it; watch the releases page. Signing will not silence every Windows warning at once, because SmartScreen keeps warning about new downloads until they earn a reputation, signed or not.
[!WARNING] Turning Smart App Control off cannot be undone Windows will not turn Smart App Control back on without a reset or reinstall, so weigh that against simply waiting. 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.
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.
*-setup.exe installer is the easiest option.C:\Apps\Libation). Do not copy new files on top of the old install folder.%UserProfile%\Libation (or the path in appsettings.json -> LibationFiles) are separate and should still work.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%.
Sync clients replace files with placeholders, restore old copies, and leave conflict copies behind. Inside an install folder that breaks in-app upgrades, and inside your Libation data folder it can corrupt the search index.
Hangover.exe is located in the folder containing Libation.exe. Double-click it to run it.
Hangover is located inside the app bundle. Either:
open /Applications/Libation.app --args hangoverApp 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; unofficial upgrades are not supported, and the steps below are community-tested workarounds.
Try the following in order:
xattr -cr /Applications/Libation.app
open failed (for example with error -128):
/Applications/Libation.app/Contents/MacOS/Libation
/Applications/Libation.app/Contents/MacOS/Libation > ~/Desktop/libation_debug.log 2>&1
open /Applications/Libation.app --args hangover fails, run Hangover from the bundle using Finder (see option 2 under Hangover above).The installer creates shortcuts for libation, libationcli, and hangover. From a terminal, run hangover.
If the Linux UI is tiny, try AVALONIA_GLOBAL_SCALE_FACTOR=2 libation (tune the number); see #634.
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 (section: Runtime dependencies (Audible sign-in)).
On some Linux setups the home directory or default temp area sits on a stacked or encrypted filesystem. That often means a shorter usable path length than a plain ext4 mount. Together with a deep Books folder or long paths from naming templates, Libation can fail during or after decryption when moving finished files into the library.
What to try: In Settings -> Download/Decrypt, set Books and the in-progress / temporary location (the folder used while files are downloaded and decrypted) to shorter paths on a normal, unencrypted volume if you can—for example an external drive mounted without an extra encryption layer. A user on Mint described this approach in GitHub issue #1199 (that thread also mentions MissingMethodException, which usually indicates a mismatched or partial install rather than path length alone).
Symptoms include a crash on startup that mentions LibationContext.db under a path like ~/snap/libation/<number>/.local/share/Libation/.
Permissions - The whole Libation data directory must be writable by your user, including LibationContext.db, LibationContext.db-wal, and LibationContext.db-shm when they exist. Fix ownership with chown if needed.
Stale LibationFiles after a Snap refresh - Snap may install a new revision folder (new <number>) while appsettings.json inside the new folder still points LibationFiles at the previous revision path. Libation then targets the old path while the app runs from the new revision, which often surfaces as a read-only or migration failure even when permissions on both trees look fine.
Fix: edit appsettings.json in the active revision (for example under ~/snap/libation/current/...) so the LibationFiles value uses the same .../snap/libation/<number>/... as that file, or use LIBATION_FILES_DIR. Step-by-step context: Install on Linux - Snap and issue #1776.
Non-Snap build - If you still suspect Snap confinement after the above, try a .deb / .rpm / AppImage build from Releases to compare behavior.
These errors come from Audible refusing to grant a download license. Common causes:
After a refusal Libation waits before asking about that title again, so you see the explanation once rather than on every run. It attempts the title again by itself; to try it sooner, name it (libationcli liberate <ASIN>) or set its download status to Not Downloaded. See Retrying titles Audible refuses.
Attach your log file when opening a GitHub issue.
Both were fixed in 13.7.9.
libationcli liberate downloaded no PDFs. A plain run only looked at titles that needed an audiobook, so a title whose audio was already downloaded was never reached and its PDF was never fetched. libationcli liberate --pdf was the only way to get them. A plain run now covers both. If your library predates the fix, one libationcli liberate (or Liberate > Begin Book and PDF Backups in the app) collects the PDFs you are missing.
PDFs went into the Books directory instead of the book's folder. Libation saves a PDF beside its audiobook, which it locates by looking for the title's ASIN in the file path. When that lookup found nothing it fell back to the Books directory itself. It now falls back to the folder the folder template names for that title.
The lookup finds nothing in two situations, and the second is worth checking:
<id> tag. Then no file Libation writes has the ASIN in its path, so Libation cannot recognise its own output for any title. Add <id> back in Settings > Download/Decrypt; the defaults are <title short> [<id>] for folders and <title> [<id>] for files. This also explains PDFs with no ASIN in the name: the file name comes from your file template.Already-misplaced PDFs are not moved. Move them into their book folders yourself, or set the affected titles' PDF status to Not Downloaded and download them again.
From 13.7.9 the log rolls every 10 MB as well as every month, keeping the 20 newest files, so the current
LogYYYYMM.log is always small enough to upload. Existing installs pick this up on the next start: Libation
fills in the size-rolling settings your Settings.json is missing without touching anything you set yourself.
Before that, rollingInterval: "Month" was the only rolling rule, so one file grew for the whole month --
tens of MB for an install with several accounts scanned on a frequent schedule, and Serilog's own 1 GB
ceiling would eventually stop it logging at all until the month rolled over.
If a single file is still too large for what you need, lower fileSizeLimitBytes (and, for total disk use,
retainedFileCountLimit) in the File sink's Args in Settings.json. See Docker -
Logging for the full sink configuration.