Troubleshooting

Troubleshooting

No permission to write in a folder the app made, or an import fails

Start here: Settings → Check folder permissions. It says who the app is writing as and what each folder lets it do — it writes a file and deletes it again rather than reading the mode and guessing:

If the owner of your library reads 0:0, the app is writing as root and that is the problem.

The container has to write as the user that owns your share. Set on the container:

Variable	Unraid
PUID	99 (nobody)
PGID	100 (users)
UMASK	000

The template has fields for all three from 1.10.16 onwards. Without them the app runs as root, and every folder it creates belongs to root with mode 755 — the app can write there and you cannot, which is why an import lands and then refuses you permission to copy anything into that folder or to move it.

An existing container does not gain those fields when you update it. Unraid keeps the configuration you saved, so the new variables are simply absent: add them by hand (Docker → the container → Edit → Add another Path, Port, Variable → Variable, PUID = 99, then again for PGID = 100 and UMASK = 000), or remove the container and add it again from the template. From 1.10.24 the app also falls back to whoever owns the appdata folder when nothing is set, which on Unraid is the same 99:100 — but the report above is how you check.

Folders already made as root have to be handed back once, on the server:

chown -R 99:100 /mnt/user/Audiobooks && chmod -R u+rwX,g+rwX /mnt/user/Audiobooks

Two other things changed in 1.10.16, in case you saw them:

• "the directory was not empty" — a rename that a user share spread over several disks refuses is now done as a copy instead, and a destination that already holds something is refused by name rather than as a disk error code.
• an import that copies never removes the original until every file has arrived at the same size. If it cannot finish, it says how far it got and leaves your copy alone.

My authors are in the Genres column

The library folder is one level too deep: you added a genre folder without ticking Is a Genre, so its authors were read as genres. A scan says so in the bar at the bottom:

…/Fantasy looks like a single genre folder, so its authors are being filed as genres. Tick "Is a Genre" behind it in Settings, or add the folder that contains your genre folders instead.

Tick it, or add the parent folder instead, and scan again. Nothing on disk was touched — only the database was wrong.

Updating the container lost its paths, password and API key

The template file my-My-Audiobook-Collection.xml in /boot/config/plugins/dockerMan/templates-user/ is where Unraid keeps your settings for this container. Copying the repository's copy of that file over it replaces your values with empty defaults, and the next update then recreates the container without its paths.

To put it back: Docker → the container → Edit, fill in the port, /data, /audiobooks, the import folder and the two variables again, then Apply. Nothing in /data or in your audiobooks was affected, so users, positions, listened marks and covers are all still there, and the collection comes straight back.

Then leave the file alone: change settings in Unraid's form, not by copying the template again. Only copy it in on a server that does not have the container yet.

A scan found fewer books than I have

Scan the library and look at Not counted in the left column. It is there whenever the last scan walked past a folder, and it names every one, why, and where it is:

It says	What to do
a folder deeper than the layout reads	the audio is below genre / author / series / part / book. A series published in parts is read (see How your folders are read), so this means either one level deeper again, or a folder whose contents are not all books — a boxed set with a stray folder in it, for instance. Press File this book… on the row, or move those book folders up a level yourself
files this app does not read	it lists the kinds it found. .mp3 .m4a .m4b .ogg .flac .opus are read; .aax and .wma are not — convert them
nothing to read in it	an empty folder. Nothing to do, or delete it
audio outside a book folder	loose files straight in a genre or author folder. Press File this book… to give them a folder of their own
set aside by an import	a Not Imported - or Replaced - copy. Deliberate — delete it when you no longer want it, or press File this book… to keep it after all
the folder could not be read	a permission problem on the share, with the error the disk gave

Nothing in that list is deleted or changed by looking at it. The report is what the last scan found, so it is empty until you scan, and after a container restart.

Putting one right without leaving the page

The three reasons that are a filing problem — a folder too deep, audio outside a book folder, and a copy set aside by an import — carry a File this book… button:

The genre, author, series and title are already filled in from the folders it sits in and, for anything they did not say, from the tags of its first file. Correct whatever is wrong and press File it:

• the audio moves into genre / author / series / title,
• the book joins the library at once — no scan needed,
• and unless you untick it, those same words are written into the files, so the next scan reads the same thing and the book stays where you put it.

Files spread over more than one sub-folder are put together in order with the sub-folder's name in front of each, so a boxed set keeps its discs apart. A book that is already in the right place and only sits one folder too deep is flattened where it is.

It refuses, and moves nothing, if the folder has gone in the meantime, has no audio in it, or if there is already a book where you are sending it. The genre is a dropdown of the genre folders you have, so a typo cannot invent a genre.

Nothing appears after a scan

• Is a library folder set, and does it exist inside the container? /audiobooks, not /mnt/user/Audiobooks.
• Are the books three levels down (genre / author / book) or four with a series? Two levels down needs Is a Genre.
• Are the files one of .mp3 .m4a .m4b .ogg .flac .opus?
• Does the bar at the bottom report an error? A permission problem on the share shows up there.

A book turns up as a series, or a series as one book

The rules are exact, and How your folders are read lists them. The usual cases:

• a folder holding one sub-folder is read as one book, not a series of one
• sub-folders all named Disc 01, CD 2, Part 3 are read as one book with all its discs in order
• anything else with several sub-folders is a series

Find metadata says there is no API key

GOOGLE_API_KEY is not set on the container, or it was set and the container was not restarted. It is set on the container only — there is no field for it in Settings. See Settings reference.

Other messages from a lookup mean what they say: a rejected key, a Books API that is not enabled for that key, an IP restriction on the key, or a daily quota that is used up. A 503 is Google being busy; it is retried after 10, 20 and 30 seconds before it gives up.

The lookup cannot reach Google

The dialog names the failure, because each one is put right in a different place:

• cannot look up www.googleapis.com (ENOTFOUND / EAI_AGAIN) — the container has no resolver it can reach. It inherits one from the host, so read /etc/resolv.conf on the server first: see Tailscale takes the DNS over below, which is the commonest reason for this one. On a custom network (br0) a container needs a DNS server of its own.
• no answer within fifteen seconds — the name resolved and nothing answered: outbound HTTPS is being dropped somewhere between the container and the internet.
• refused or dropped (ECONNREFUSED, ENETUNREACH…) — something is blocking outbound HTTPS.
• the secure connection could not be made (CERT_…) — a proxy or filter is intercepting HTTPS and its certificate is not trusted inside the container.

To see it from the server rather than the page:

docker exec my-audiobook-collection node -e "fetch('https://www.googleapis.com/books/v1/volumes?q=test').then(r=>console.log('HTTP',r.status)).catch(e=>console.log(e.cause?.code||e.message))"

A code means the network; HTTP 200 or HTTP 400 means the connection is fine and a 400 is about the key.

Tailscale takes the DNS over

If lookups worked and then stopped, and the code is EAI_AGAIN, this is almost certainly it. Start in the container:

docker exec my-audiobook-collection cat /etc/resolv.conf

# Generated by Docker Engine.
nameserver 100.100.100.100
search your-tailnet.ts.net
# Based on host file: '/etc/resolv.conf' (legacy)
# Overrides: []

100.100.100.100 is Tailscale's MagicDNS, and the last two lines say where it came from. Overrides: [] means nothing was set on this container. Based on host file means Docker copied it from the server. So the host has accepted Tailscale's DNS, and every container on the machine inherits that address — which a container cannot reach, because MagicDNS answers on the host's Tailscale interface only. Every name fails, while the server itself resolves everything.

One command on the host puts it right:

tailscale set --accept-dns=false

That is kept in tailscaled's own preferences and survives a reboot. The host goes back to its configured resolvers, every container inherits a working one, and nothing needs setting per container. The price: the host stops resolving *.ts.net names itself. Tailnet machines stay reachable on their 100.x addresses, and Tailscale Serve to a container is not affected.

Two things that look like the fix and are not:

• Tailscale Extra Parameters, or a Use Tailscale DNS pulldown, on the container. Those are for a Tailscale running inside the container, and Overrides: [] shows that is not what wrote this resolver.
• Override DNS servers in the Tailscale admin console. That decides which nameservers MagicDNS hands your clients, not whether a container can reach MagicDNS at all.

To leave the host as it is, give this one container its own resolver instead: --dns=1.1.1.1 in the container's Extra Parameters (the Docker field, with Advanced View on). It fixes this container and no others.

Needs tags still shows the same number

Work through these in order — the first two were bugs, fixed in the versions named, so start by checking which version you are running: it is at the right-hand end of the status line along the bottom of the page.

• Fixed in 1.9.64: cover art beside the audio — a cover.jpg or folder.jpg in the book's folder — was never written into the files, so a book with folder art kept asking for a cover however often you wrote tags or scanned.
• Fixed in 1.9.56: the count was reloaded only when the page was, so a finished scan appeared to change nothing. A scan also takes the values of tags written by another program now, not only the fact that they are there.
• If the number is right but higher than you expect, open Needs tags and read a row: it says what a write can fix now and what is not known yet. A book with no year, description or cover art anywhere still needs those, and writing tags cannot invent them — Find metadata can.
• A book counts as done only when its files carry all of album, title, artist, album artist, genre, year, description, cover and track number.

The page jumps away when I apply metadata from Needs tags

Fixed in 1.10.0. Applying metadata to a book from a maintenance list used to leave the list and show the library instead — or the shelves, if a genre came with the metadata. The list now stays where it was.

The tags did not change

• Tag writing is MP3 only. An .m4b is read and played, never written.
• Is the /audiobooks mount read/write? Read-only is exactly what a silent failure looks like.
• The green badge is rebuilt from what actually landed in the files, so if it still lists fewer tags than you expected, the write did not take.

A cover will not update

Covers are named after the image itself and served with a long cache time, so a different image always gets a new URL — but a browser that already has the page open may keep showing the old one until a reload. Ctrl+F5 settles it.

A button in the header is missing, or an old one is still there

The page is cached in your browser. Reload with Ctrl+F5 after an update. If a control you expect from the release notes is still missing after that, the container itself is still running an older image — Force update in the Docker tab's Advanced View.

Browsing feels slow

• The page reads its lists on open; a very large import folder used to be read on every page load and no longer is.
• Covers are cached for a week, so the first visit after an update is the slow one.
• A scan running in the background competes with browsing on the same share. Wait for the bar to finish. It reads several books at once, which is what makes it three times faster on a share than it used to be, and also why it is the busiest thing the app ever does to your disk.
• Writing tags into the whole collection runs on threads of its own, so the pages stay answerable while it works. If they do not, the share itself is the limit.

Something is refused with "Only the admin can change things here"

The browser has not unlocked. Press Admin on the listening page and enter the password, or open the admin page and unlock there. See Sharing with others.

Two people hear each other's positions

They are using the same name. Names are the only thing keeping positions apart — pick a different one in the header dropdown.

The port is already in use

Change the host port in the container's settings; the WebUI link follows it. The port inside the container is 8523 unless PORT says otherwise.

A series does not show up

Scan the library. A series is worked out while scanning, so books that were already there need one pass before it appears — the folders do not have to change for that.

If it still does not appear, the collection may not be saying it anywhere: How your folders are read lists the three places a series can come from. A series folder always works, and the Series field in Edit metadata makes one — filling it in for two books files them both under it.

A book will not play, or plays silence

Run Check every book against the disk in Settings. It opens every file and lists what it cannot read under Broken on disk, with the number of files involved — a download that stopped halfway looks exactly like a good book to a scan. From that list you can re-check a book after repairing it, or delete it.

The covers folder keeps growing

Every time a book gets different artwork, the old image stays behind under its own name. Settings → Tidy up unused covers moves everything nothing points at into covers/duplicates, and offers to delete or zip that folder once it holds more than a thousand files. See Settings reference.

Where is my data?

/data holds library.db (the collection, users, positions, listened marks, the trash record and the replaced record) and covers/. Your audiobooks are never copied there. Losing /data costs you the positions and listened marks; a rescan rebuilds everything else.