Estimated reading time: 2 minutes

A few days ago I ran into a curious problem: Pi-hole running on Docker, inside my NAS based OpenMediaVault, kept throwing unexplained errors in the log pihole-FTL. Everything apparently worked, but lines like these appeared in the log:

ERROR: SQLite3: disk I/O error in "SELECT VALUE FROM ftl WHERE id = 0;"
WARNING: Database not available, please ensure the database is unlocked when starting pihole-FTL !

or again:

ERROR: SQLite3: os_unix.c:43514: (19) mmap(/etc/pihole/pihole-FTL.db-shm)

After a bit of research and testing I realized the problem wasn't Pi-hole, born Docker, but mergerfs, the filesystem I use to merge multiple disks into a single share.

---

The problem

For those who don't know him, mergerfs is a union filesystem based on FUSE, very convenient for creating a large "virtual" volume starting from multiple physical disks. I've been using it for years on OpenMediaVault to aggregate my data and backup discs.

However, there is a small detail: FUSE does not handle shared memory operations well (mmap) which some programs use to quickly access database files. And among these programs there is, coincidentally, own Pi-hole.

The offending file is /etc/pihole/pihole-FTL.db, un database SQLite where FTL saves statistics, queries and network devices. When this file is in a directory mounted via mergerfs, SQLite tries to use mmap() sul database, but mergerfs responds with an I/O error… and the result is a Pi-hole that keeps complaining.

---

The solution

The solution is actually simple: avoid running the database through mergerfs.

In my case I had mounted the Pi-hole configuration directories like this:

volumes:
  - ./etc-pihole:/etc/pihole
  - ./etc-dnsmasq.d:/etc/dnsmasq.d

These folders were located under a mergerfs share (/srv/mergerfs/main_share), and then Pi-hole wrote the database to a “virtual” path. The trick was to replace those paths with i absolute paths of the real disk, bypassando mergerfs.

Here's how:

services:
  pihole:
    image: pihole/pihole:latest
    container_name: pihole
    volumes:
      - /srv/dev-disk-by-uuid-XXXX/etc-pihole:/etc/pihole
      - /srv/dev-disk-by-uuid-XXXX/etc-dnsmasq.d:/etc/dnsmasq.d

(Dove XXXX is the UUID of the physical disk on which you want to save the Pi-hole files.)

---

Practical steps

For safety, I followed these steps:

1. I stopped the container:

   • docker compose down

2. I moved the old database (the corrupt one):

   • mv /srv/dev-disk-by-uuid-XXXX/etc-pihole/pihole-FTL.db* /srv/dev-disk-by-uuid-XXXX/etc-pihole/backup/

3. I restarted Pi-hole:

   • docker compose up -d

Pi-hole automatically recreated a new database and, from that moment, no “disk I/O” errors it no longer appeared in the log.

---

Conclusions

Basically, Pi-hole and mergerfs can coexist without any problems — just know that SQLite databases don't like being hosted on FUSE filesystems. If you have similar errors with other containers too (for example Home Assistant or Nextcloud AIO), try moving the files .db on a real disk and you'll see them disappear.

The rest — configurations, log, blocklists — can safely remain under mergerfs.

Note: you can still include Pi-hole directories in your mergerfs volume for automatic backups, as long as the container physically writes elsewhere.