SQLite Databases on a NAS Share: Why Containers Lock or Corrupt Their Config Over NFS and SMB
Felix Braun
November 16, 2026
You moved your containers’ config folders onto the NAS so everything would live in one place with one backup job, and now things are going wrong. Sonarr logs “database is locked,” Jellyfin takes ages to load a library page, or a container that ran fine for months refuses to start with “database disk image is malformed.” The app and Docker are rarely to blame. Many homelab apps store their state in SQLite, and SQLite was never designed to run over NFS or SMB. This guide explains why, how to confirm that’s what you are seeing, and how to move the data somewhere safe without losing it.
Error messages that point at storage, not the app
The symptoms vary by app, but they fall into a few recognizable groups:
- “database is locked” (SQLite’s
SQLITE_BUSY). A write could not get the lock it needed in time. On a network share it can also mean the lock request to the file server came back slowly, or never. - “database disk image is malformed” (
SQLITE_CORRUPT). Pages inside the file don’t agree with each other. This is real damage, not a timeout, often surfacing after a NAS reboot or network blip during a write. - A slow or frozen UI. Every page view in an app like Sonarr or Jellyfin runs many small queries, and each one turns into file reads that now cross the network.
If you see any of these and the app’s config directory is a bind mount to an NFS or SMB path (or a Docker volume backed by NFS or CIFS through driver_opts, which amounts to the same thing), start with storage before you touch app settings.
Homelab containers that keep a SQLite database in their config folder
Most of the popular self-hosted apps use SQLite by default, and the database sits in the path you mount as config or data:
- Sonarr and Radarr keep their main database (
sonarr.db,radarr.db) in the/configmount. The Servarr wiki says the AppData folder “MUST be on local storage” and warns that SQLite on a network drive will eventually produce a malformed database. Both can use PostgreSQL instead, though the wiki notes the apps don’t back up a Postgres database for you. - Jellyfin uses SQLite for its database today. Its storage documentation says the database should be stored locally and not on a network storage device, even though media can sit on an NFS or SMB mount.
- Plex Media Server keeps its library database (
com.plexapp.plugins.library.db) in the Plug-in Support folder inside its data directory. The consistent advice on Plex’s own forums is to keep that directory on locally attached storage. - Home Assistant uses SQLite by default for the recorder, stored as
home-assistant_v2.dbin/config. You can point the recorder at MariaDB or PostgreSQL withdb_url. - Vaultwarden stores almost all of its state in
db.sqlite3in the data folder, with-waland-shmfiles next to it when present. MySQL and PostgreSQL are supported alternatives. - Uptime Kuma keeps its data under
/app/data, and its README says plainly that file systems like NFS are not supported and you should map a local directory or volume.
If you aren’t sure about an app, list the config directory and look for .db, .sqlite or .sqlite3 files, especially ones with -wal or -shm files beside them.
What sqlite.org says about network filesystems
SQLite’s documentation covers this directly. The page on using SQLite over a network advises against putting a database file on a network filesystem. SQLite relies on two things from the operating system: reliable sync (data really reaches the disk when it asks) and working file locks. Network filesystems implement both less reliably than local disks, and the docs note that this has led to database corruption. The same page puts it simply: “SQLite is designed for situations where the data and application coexist on the same machine.”
The page also makes a point that explains why problems show up late. Slowness, it says, is the least important issue with network filesystems. The bigger risk is that failures in the file I/O path, rather than in the application’s own requests, can corrupt the database instead of simply rolling back a transaction. For simultaneous reads and writes from more than one client, it recommends a client/server database such as PostgreSQL or keeping all access on the machine that owns the file.
SQLite’s “How To Corrupt An SQLite Database File” page names the cause directly: some filesystems have bugs in their locking logic, and it says this is especially true of network filesystems and NFS in particular. If two processes believe they hold a lock that the filesystem didn’t actually enforce, both can write, and the file ends up inconsistent.
You might reasonably think: “Only one container ever opens this file, so locking doesn’t matter.” Often that’s true and the setup works for a while. But a single container can still have several processes or threads touching the database, backup jobs on the NAS may read the files while the app writes, and the sync guarantees still depend on the network and the file server.

Why WAL mode needs every process on the same host
Many apps switch SQLite into write-ahead log (WAL) mode for better concurrency. In WAL mode, writes go to a -wal file next to the database, and readers use a small index kept in the -shm file, which SQLite memory-maps so that every connection shares it.
The WAL documentation lists the consequence as the first disadvantage: all processes using the database must be on the same host, and WAL does not work over a network filesystem, because processes on different machines can’t share memory.
Two more details from that page matter for homelab setups:
- The
-walfile is part of the database’s persistent state. If you copy or move the database without it, committed transactions can be lost or the database can end up corrupted. - Never delete a
-walor-shmfile to “fix” a lock error. The only safe way to clear a WAL file is to open the database with SQLite and close it cleanly, which checkpoints the log back into the main file.
The Servarr wiki adds a related trap: if you pool disks with mergerfs, the direct_io option breaks SQLite, because SQLite uses mmap and direct_io does not support it.
Mount options that hide the problem instead of fixing it
Search for “database is locked” with NFS or CIFS and you’ll find advice to change mount options. Most of it makes the error go away by weakening locking:
- NFS
nolock. The Linuxnfs(5)man page explains that withnolock, locks only provide exclusion against other applications on the same client. Remote processes are not affected. That removes the lock round trip, and with it any protection against a second client or a NAS-side process. - CIFS
nobrl. According tomount.cifs(8), this stops the client from sending byte-range lock requests to the server. It exists for applications that break with CIFS-style mandatory locks. SQLite then believes it has locks that the server never saw. - Moving to NFSv4. NFSv4 has locking built into the protocol instead of the separate NLM sideband used by v3, and Jellyfin’s docs recommend it for playback performance problems related to locking. It’s a better protocol, but it doesn’t change SQLite’s position that network filesystems are not a supported home for a live database.
None of these options make the share safe. They change which failure you see. If an option makes “database is locked” disappear, assume your locks now protect less than before.
The fix: config on local disk, media on the share
The reliable layout splits the two kinds of data. Small, write-heavy app state (databases, caches, metadata) goes on storage the Docker host owns directly, ideally an SSD. Large, mostly read media stays on the NAS, mounted into the container as a separate path.
services:
sonarr:
image: lscr.io/linuxserver/sonarr:latest
volumes:
- /opt/appdata/sonarr:/config # local SSD on the Docker host
- /mnt/nas/media/tv:/tv # NFS or SMB mount from the NAS
- /mnt/nas/media/downloads:/downloads
To move an existing app without losing data:
- Stop the container with
docker compose stop sonarrand confirm it’s down. A database copied while the app is writing can be inconsistent. - Copy the whole config directory, including every
-waland-shmfile, to local storage. Preserve ownership withrsync -aorcp -a. - Run an integrity check on the local copy (see the next section) before you trust it.
- Change the bind mount in your compose file to the local path, start the container and check the logs.
- Keep the old copy on the NAS until the app has run cleanly for a while, then delete it.
If the Docker host is a small NAS with only spinning disks, local disk is still better than a network share for this purpose. If you’re deciding whether containers belong on the NAS or a separate box with an SSD, NAS vs mini PC for Docker containers covers the trade-offs.

When the Docker host has no local disk: block storage instead of a file share
Sometimes the compute node really has no useful local storage: a diskless mini PC, or a cluster where containers need to move between hosts. In that case, give the host a block device rather than a file share.
With iSCSI (or a VM disk image stored on the NAS), the NAS exports raw blocks and the Docker host puts its own local filesystem, such as ext4 or XFS, on top. SQLite then sees an ordinary local filesystem with normal locking and mmap semantics, because the client kernel owns the filesystem. This is also why a Proxmox VM whose disk lives on NFS storage doesn’t have this problem: the guest sees a block device, not a network share.
The rule that comes with block storage is strict: only one host may mount that filesystem at a time. Two machines mounting the same ext4 LUN will corrupt it far faster than SQLite on NFS ever would.
The other option is to change the database. Sonarr, Radarr, Home Assistant and Vaultwarden can all use a PostgreSQL or MariaDB server, which owns its files locally and serves clients over the network the way SQLite’s docs recommend.
Checking a database and recovering a damaged one
Do these steps on a copy, with the app stopped. Many app images don’t include the sqlite3 command-line tool (Vaultwarden’s docs mention this), so install it on the host and work on the files from there.
Start with an integrity check:
sqlite3 /opt/appdata/sonarr/sonarr.db "PRAGMA integrity_check;"
A healthy database returns a single line: ok. Anything else lists the problems it found. PRAGMA quick_check; runs faster and skips some checks, which is useful on large Plex or Jellyfin databases.
If the check fails, the order of options is:
- Restore the app’s own backup. Sonarr, Radarr and several others write scheduled backups into a
Backupsfolder inside config. Check those withintegrity_checktoo; a backup taken after the corruption started may be damaged as well. - Try SQLite’s recovery command. The CLI’s
.recoverreads as much data as it can from a damaged file and writes it out as SQL you can load into a new database:
sqlite3 sonarr.db ".recover" | sqlite3 sonarr-recovered.db
sqlite3 sonarr-recovered.db "PRAGMA integrity_check;"
The Servarr wiki points to .recover for exactly this error. Recovered databases can be missing rows, so check that the app starts and that recent changes are present before you swap the file in. If neither works, the last resort is a fresh database and re-importing your library, which is why the backups below matter.
Recovering the file without moving it off the share only resets the clock, so relocate first.
Backing up a live SQLite file the safe way
Keeping appdata local doesn’t mean leaving it out of your backups. It means the NAS should receive a consistent copy rather than host the live file. SQLite’s own guidance is that copying the raw file while a transaction is active can produce a backup that mixes old and new pages. Use one of the methods built for a live database:
# Online backup API, safe while the app is running
sqlite3 /opt/appdata/vaultwarden/db.sqlite3 ".backup '/mnt/nas/backups/vaultwarden-$(date +%F).sqlite3'"
# Or a compacted copy
sqlite3 /opt/appdata/vaultwarden/db.sqlite3 "VACUUM INTO '/mnt/nas/backups/vaultwarden-$(date +%F).sqlite3'"
Writing the finished backup file to the NAS is fine: it’s a single file written once and read later, with no other process locking it. Vaultwarden’s wiki recommends .backup for the same reason, and newer Vaultwarden releases also include a built-in /vaultwarden backup command you can run with docker exec.
Schedule the dump from cron on the Docker host, then let your file-level tool pick up the dump folder. The pattern of dumping first and snapshotting second is covered in more depth in dumping Postgres and SQLite before the snapshot, and if you still need a tool to ship those dumps off-site, see Kopia vs restic. Run PRAGMA integrity_check on a restored copy now and then. That’s the only way to know the backups are actually usable.
The short version of the layout is simple: databases live next to the process that writes them, media lives on the NAS, and consistent dumps travel from one to the other. Once config sits on local storage, “database is locked” usually goes back to being a rare, brief event instead of a daily one.