Database error : File library/metadata.db not found

[bcameron21]

My COPS add-on has recently stopped. It was previously - until a few weeks ago - working perfectly. I have not changed any of the Add-On config, but it has stopped working correctly. I'm not sure if this is due to the version 2.0 update of the Add-On, the the HA OS update to version 17.

I am getting a Database error, and at the bottom of the page it says "File library/metadata.db not found".
I don't see any errors in the logs.

I have the library on a Synology NAS and it is linked to Home Assistant network storage (media) using NFS. The name of the share is "books" and I use "books" as the library folder location. My metadata.db is in the root directly of the share. I can access the /media/books folder via a samba share without any problem. I've tried different paths for the library folder location, and also tried changing the network storage type from "media" to "share", along with changes to the path name. None of these are making any difference.

[dunxd]

I'm sorry you are seeing this. It does seem likely this is caused by the 2.0 version of HA COPS.

COPS looks for the metadata.db file in the root of the share which it sounds like you have correctly.

However, I am unable to replicate the error with HA COPS 2.1.1 (which uses COPS 4.1.0) on my own server - the database is being read fine. I am getting an error with downloading book files from the web pages, which is either related to nginx mimetype serving or PHP caching.

It would be very helpful if you could confirm what version of HA COPS you are running, from the App info page in Home Assistant.

[dunxd]

@bcameron21 do you still see this issue with 2.2.2?

[bcameron21]

I have been running the latest version and have updated to 2.2.2.

It's still not working & I still get the "database error" / "library/metadata.db not found" errors.

I can access the share on the Home Assistant URL at \HA IP address\media\books, and the metadata.db file is visible there in the root directory.

I'm now also noticing an error in the logs which I didn't spot before.

[08/Mar/2026:19:15:43 +0200] "GET /check?err=1 HTTP/1.1" 200 4191 "-" "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/145.0.0.0 Safari/537.36"

It also shows up in the "Check if the base URL looks OK" section of the error page:
REQUEST_URI: /check?err=1

[dunxd]

The check page in COPS (e.g. http://localhost:8000/check runs the checks, then appends ?err=1 if it finds any errors. The log you are seeing just shows that URL being served, which isn't an error in itself.

Note that if you refresh the check page with check?err=1 in the URL it will still report an error at the top of the page even if you fixed it.

It sounds like COPS cannot read the files in media/library or at least the metadata.db file. This may be down to permissions - the new method for running HA COPS on v2 access the files using different user accounts, and these users may not have the right level of access to things in your share. Try setting the files and folder in the share to allow all users to read everything. Depending on how your NAS works, you may also need to set folders to allow execution, otherwise they can be seen but not opened.

Try this and let me know if it fixes things. If so I will update the docs to clearly state the required permssions on shares.

[dunxd]

@bcameron21 it sounds like Read access on a Synology NAS is enough to open folders. So if you give Everyone/Guest read access to everything in your share this should be enough. Let me know what happens when you do this.

You may also be able to see in the logs of your NAS failed attempts to access the metadata.db and other items under the library share. This would be a smoking gun to permissions being the issue.

[bcameron21]

I tried to do some more troubleshooting on this. So far no success.

I don't see any access attempts to the NFS share I use for COPS in the Synology log.
I do see the Synology DSM integration access. This is based on a User account which I created specfically for Home Assistant, and that account has 2FA.
This led me to notice that my config for Home Assistant Backups uses the Synology DSM integration. I had orginally setup a Backups Storage connection using Synology NFS (like I'm doing for COPS), but while that storage connection is there it isn't actually being used, so I don't know if that's still working either.

My calibre folder is connected to Home Assistant storage via an NFS share.
That currently gives me the following configuration options on Synology (DSM version 7.3.1)

• Hostname or IP: my HA IP address
• Privilege: Read/Write
• Squash: no mapping (i.e. to admin or guest)
• Security: sys/AUTH_SYS (no Kerebos options selected)
• Enable asynchronous: True
• Allow connections from non-privileged ports (ports higher than 1024): False - I tried changing this to True - made no difference
• Allow users to access mounted subfolders: False - I tried changing this to True - made no difference

I also realised that something in the Synology 7.3 DSM upgrade may have broken the setup as that was also around the time I noticed the COPS stopped working.

I tried adding additional NFS share permissions for an internal IP address on the COPS Check page. I'm guessing this is the IP of the Docker container. That didn't seem to help either.

I tried to configure my Storage connection to Synology to use CIFS, but I'm struggling to get that to work with my 2FA on the account enabled. Probably this is why I reverted to using NFS here. Maybe the Synology DSM integration is handling the 2FA better than the Storage mount. There is probably a way to make this work without disabling 2FA on the account, but so far I haven't managed to figure that out. I haven't tested a Synology account with 2FA disabled yet, but I'll try that next.

[dunxd]

The HA COPS app does not handle authentication to any mount share. This is all handled by Home Assistant. It should be possible to browse the mount via the Home Assistant UI via the Home Assistant UI - go to settings then click the search button and search for Media. Pick Media navigate. This will allow you to browse the media directory which should have your mount in it - probably inside the My Media folder.

• If you cannot see it at all then the mount isnt working at all.
• If you see it but are unable to browse within it then there is a permission problem.
• If you can browse it and see book folders then the issue is likely with HA COPS. Note that the browser only displays media files recognised by Home Assistant - you won't see metadata.db or epub files but you should see book folders and cover.jpg files.

You shouldn't need to allow the internal docker IP address - it is the Home Assistant server that accesses the share. The app then accesses the mount - it doesnt talk directly to the share source.

Let me know what you find. Im happy to.help you get this working and learn what needs to be in place to make shares on Synology NAS work for HA COPS.

[bcameron21]

Thanks for persisting with trying to solve this.

As mentioned before I can browse the NFS shared storage on the Home Assistant server at \HA IP\media\books

Initially I couldn't see the share in the media browser. http://HA IP/media-browser/browser

I added the following the line to my configuration YAML, and it shows up fine in the media browser (in the My Media folder)

homeassistant:
  media_dirs:
    books: /media/books 

Alas this hasn't fixed the error with COPS.

I still haven't tried setting up the Shared Storage using CIFS/Samba. Just haven't had time for that yet.

[dunxd]

I dont have those lines in my configuration.yaml so I have no idea if they are related to Home Assistant addon access to files in /media.

When you go to the media browser and click on My Media this shows you what is visible to Home Assistant in /media. Does your library folder appear there with exactly the name you set in the HA COPS app config page? When you open it do you see folders with your author names?

Sorry for all the questions. I dont have a Synology NAS and the devcontainer for developing apps doesnt support mounts so it is tricky for me to troubleshoot this. I should be able to give it more time at the weekend.

[dunxd]

I've done some testing by sharing the Calibre Library folder on my mac, mounting it to a folder in `/media' in Home Assistant, and configuring this is the library folder in HA COPS. This uses SMB/CIFS rather than NFS. I am not seeing the issues you report - I can browse my library ok, although performance is a bit slow.

I have added an older version of HA COPS to the repository - v2.1.1 is prior to adding the s6-overlay system which was the major change I made with version 2.2. I've done this so you can test out whether that older version works better with your setup. To install this:

• enable the Advanced toggle in your Home Assistant profile
• go to Add-on store, click on ... and then check for updates. You should then see the older versions of HA COPS.
• installing v2.1.1.
• Make sure to stop the current version of HA COPS.
• Configure v2.1.1
• start it

Let me know if you are then able to access your library via the HA COPS web ui.

[dunxd]

I changed my Mac share from CIFS to NFS and I now also get the database not found error that you see. I will look into whether this can be fixed.

[dunxd]

@bcameron21 I have managed to get HA COPS working with an NFS share on my Mac - I had to change some settings on the share at the Mac end to get it working. Maybe you can make the equivalent changes on the Synology to get the same.

This is what I did:

• Treat the user:group making the connection as root:wheel by adding -maproot=root:wheel to the NFS share config - this is the equivalent of the Squash setting in your Synology - on your Synology, set Squash to Map all users to admin or Map root to admin
• Enable asynchronous with the -async flag - you already have this enabled on your Synology. This reduces the time the database spends waiting for the network to "confirm" every tiny read.
• Allow local file locking with the -locallocks flag - on Synology this may be handled by NFSv4.1. If you can only use NFSv3 there may be a nolock setting.
• You probably also need to Allow connections from non-priviliged ports as HA may use a port higher than 1024 which is non-priviliged.
• You may also need to enable Allow users to access mounted subfolders - I doubt this is related to metadata.db access as this is in the root of the share you made, but all your bookfiles are in subfolders, so if you stop seeing the error, but cannot download book files or read the books in the web viewer, try enabling this.

Since this likely stopped working with the switch of HA COPS to using NGINX the issue is likely due to the user:group used to identify access to the mounted files, so perhaps the squash setting is all you need - start with that and move on to each of the other settings if you still get problems.

I'd love to hear what you find.

I have noticed that the performance of HA COPS is not good with NFS mounts though, at least in my environment. The web interface is very slow - it has to read the metadata.db file and this seems to be quite slow. SMB seems a bit better. Local storage of the files is zippy compared to either.

[bcameron21]

Thanks for all the effort you've gone to narrow this down.
I've got it working now.

The critical setting is:
In the Shared Folder, NFS Permissions - Set: Squash: Map all users to admin. (Map root to admin didn't work).

It seems that it helps to enable NFSv4.1. In my Synology setup I hadn't changed this setting before and it was defaulted to NFSv3. Setting to NFSv4.1 seems to make it more stable and responsive.
This setting is in File Services, NFS - Set: Maximum NFS protocol to NFSv4.1.

I also tested the other settings.

• Allow connections from non-priviliged ports - Doesn't seem to make a difference if it's on or off. It was off previously so I've left it off now.
• Allow users to access mounted subfolders - Doesn't seem to make a difference if it's on or off. It was off previously so I've left it off now.
• Enable Asynchronous Doesn't seem to make a difference if it's on or off. It was on previously so I've left it on.

Other settings I've left as-is:

• Privilege : Read/Write
• Security : AUTH_SYS

[dunxd]

That's great new. I have been having some stability issues with running HA COPS from the NFS share on my Mac. This may be related to how Macs handle power saving, and the impact this has on shares, but it is also possibly a weakness of Home Assistant mounts and the way HA COPS works. Please let me know after a week or so if your setup seems stable or not.