Fix SQLITE_FULL: SQLite database or disk is full

SQLite throws SQLITE_FULL when disk space runs out, but WAL mode can also trip it on the wrong journal size. Here's how to reclaim space and stop it recurring.

Quick answer

If you're on WAL mode, run PRAGMA wal_checkpoint(TRUNCATE); and set PRAGMA journal_size_limit = 0; to truncate the WAL file back to zero. Then check actual free disk space with df -h.

I've hit this error more times than I care to admit. It's infuriating because the message says "disk is full" but you've got gigabytes free. The real culprit is usually the Write-Ahead Log (WAL) file, which can balloon to hundreds of MB or even GBs without you noticing. SQLite doesn't shrink it automatically unless you checkpoint with truncation. I've seen this on a small Raspberry Pi running a Home Assistant database—the WAL file ate up the entire SD card. Also, some filesystems, like older FAT32 or certain network drives, have file size limits that trigger this even when space is free.

Why this happens

SQLite in WAL mode writes changes to a separate .db-wal file. When you run a checkpoint, it merges the WAL back into the main database. But the default checkpoint only truncates the WAL if journal_size_limit is zero—otherwise it keeps the file around for reuse. Over time, the WAL grows with each write, and if it hits the filesystem's max file size or fills the disk, you get SQLITE_FULL.

Another common trigger is a full temp directory. SQLite uses temp files for sorting or large transactions, and if TMPDIR points to a small partition, you'll get this error even when your database disk is fine.

Fix steps

Check disk space first. Run df -h on the database's directory and on your temp folder. If any filesystem is at 100%, free up space or move the database.
Check WAL file size. Look for .db-wal in the same directory. Use ls -lh to see if it's huge.
Run a manual checkpoint with truncation. Connect to your database and run:
```
PRAGMA wal_checkpoint(TRUNCATE);
```
This forces a checkpoint and truncates the WAL to zero size. If you're using Python, that's conn.execute("PRAGMA wal_checkpoint(TRUNCATE);").
Set journal_size_limit to zero. To stop the WAL from growing again, set:
```
PRAGMA journal_size_limit = 0;
```
This tells SQLite to keep the WAL as small as possible. You can persist this by setting it each time you connect, or use a compile-time option.
If that fails, VACUUM. VACUUM rebuilds the database and compacts it. It also resets the WAL. Run VACUUM;. Note that this locks the database and can take a while on large files.

Alternative fixes

If the error persists, try these:

Delete and recreate the WAL file. If the database isn't in use, stop the process, delete the .db-wal and .db-shm files, then reopen. This is a last resort—it can lose recent transactions if you haven't checkpointed.
Move the temp directory. Set TMPDIR to a partition with more space before starting your app. On Linux: export TMPDIR=/big/disk/tmp.
Switch to rollback journal mode. If WAL keeps causing trouble, go back to the default journal mode with PRAGMA journal_mode = DELETE;. Slower writes but simpler behavior.

Prevention

Set journal_size_limit to 0 at startup, and schedule a regular checkpoint. If you're using a server, run PRAGMA wal_checkpoint(PASSIVE); every hour or so. Also monitor disk usage—a simple cron job that warns you when disk space drops below 10% saves you from this headache. And if you're on an embedded device, consider using a lower cache_size to reduce memory pressure that can indirectly cause full temp files.

I've also found that using PRAGMA auto_vacuum = INCREMENTAL; helps keep the database file from growing forever, but it doesn't affect the WAL. Pair it with PRAGMA incremental_vacuum; after deletes. It's a bit of extra maintenance but worth it for long-running apps.

Remember, the "disk is full" error is often a red herring. Check the WAL first, and you'll save yourself an afternoon of panic.