Home / Users / Backup & troubleshooting

Backup & troubleshooting

Lexicon keeps structured data in one SQLite file and optional attachment files beside it. Copy both for a complete backup — or let the server do it for you.

Data location

Backup strategies

The SQLite database and Blob directory together form the complete Lexicon data set. Backing up only the database is not sufficient when Blob Fields are used. Prefer a backup while Lexicon is closed or a coordinated snapshot while data is not changing.

1. Close Lexicon. This guarantees the database is not mid-write.
2. Copy lexicon.db and blobs/ to safe storage — external drive, NAS, or a synced folder.
3. Version your backups — keep dated snapshots (daily or weekly) instead of overwriting a single copy:

   mkdir -p ~/backups/lexicon-$(date +%F)
   cp lexicon.db ~/backups/lexicon-$(date +%F)/
   cp -a blobs ~/backups/lexicon-$(date +%F)/

Automatic backups on the server

If you run LexiconServer, it can do the whole job for you. Automatic backups are disabled by default; give it a directory to opt in:

LexiconServer --database ~/lexicon/lexicon.db --backup-dir ~/lexicon-backups

• Every 24 hours by default (--backup-interval H), keeping the newest 14 backups (--backup-keep N); older ones are removed.
• Each backup holds a consistent copy of the database taken while the server keeps running, a portable JSON export, and the blob files the dictionary refers to.
• Files that did not change are shared between backups through hard links, so fourteen backups cost far less than fourteen copies.
• LexiconServer backup --backup-dir DIR makes one on demand — handy before an upgrade.
• LexiconServer verify-backup --path DIR reads the database's Lexicon db_version, requires the history table for schema versions that include it, and checks integrity plus every referenced file before restoration; new backups also carry database and export checksums.

Export and import

A backup of the raw files is the safest copy; an export is the portable one:

• File → Export... writes the whole dictionary as one documented JSON file, optionally with the files its blob and image values refer to.
• File → Import... merges such a file into the open dictionary: groups, types and fields are matched by name, and items that are already there are left untouched.
• The web client and the Android app offer the same two actions, and LexiconServer export and LexiconServer import do it from the command line.
• Alarms, including recurrence, linked items, ASAP and Group, review dates, links, metadata, cards and their quiz counts, named Boards, and item-field descriptions all travel with it. Export format version 7 carries all of these fields so older Lexicon releases refuse it rather than silently dropping them. See the export format.
• Exports contain current data. To preserve earlier item versions and Trash, keep the database and Blob files in a full backup.

Deletion safety rules

Blob files are deduplicated by SHA-256: multiple Item values can refer to the same physical file. Removing a value, Item, Field, or Type leaves the file in place. Use Tools → Blob maintenance…, or run LexiconServer blobs scan --database /path/lexicon.db on a server, to scan for unused files. blobs verify also hashes every file; blobs collect verifies first and removes only canonical files which are still unreferenced after a final database and content check. Back up first and preferably stop writes while collecting. Missing means a referenced file is absent; Hash mismatch means its contents are corrupt. Restore these from backup rather than deleting them. Unexpected files and symlinks are reported but not collected. The commands are local and are not available through REST or the web UI.

Lexicon uses cascade deletion for dependent records, with an application-level guard around groups. Know these rules before you delete anything:

Trash keeps a snapshot so you can restore a deleted item with its cards and surviving links. Previous saved item versions are available through History. A full database backup preserves both; a portable export contains current data only.

Changing a used field's data type explicitly warns that its values will be permanently deleted; deleting a field or type also asks first. Lexicon snapshots each affected item in History before deleting values or type assignments. The snapshot preserves the old IDs and raw values, but automatic restoration requires compatible type and field definitions. Keep complete backups of lexicon.db and blobs/ as the final recovery layer.

Troubleshooting

The app does not start

• Verify that the Qt 6 runtime is installed and matches the version Lexicon was built against.
• Ensure native SQLite and OpenSSL Crypto libraries are present.

Database errors on startup

• Check that the directory containing the executable is writable — Lexicon needs to create and update lexicon.db there.
• Make sure lexicon.db is not locked by another process (another running Lexicon instance, a DB browser, or a sync tool holding the file).

The build fails

• Confirm your compiler supports C++23 (recent GCC, Clang, or MSVC).
• Confirm CMake can find Qt6::Core and Qt6::Widgets, plus SQLite and OpenSSL Crypto — set CMAKE_PREFIX_PATH to your Qt installation if needed.
• See the developer build guide for platform details.

Still stuck?

Open an issue on GitHub with your OS, Qt version, and the exact error message.