Troubleshooting and FAQ
Causes and fixes for the messages you are most likely to meet, followed by common questions. For a backup run by systemd, read the messages with journalctl -u lmdb-lws-backup.service; the log file set by log_path has more detail.
Configuration and key errors
These stop the tool before it does anything, with exit code 2 (configuration) or 1 (key).
config: no encryption key source — set [encryption] key_env_var or key_file; refusing to run without encryption
Add one of the two keys to [encryption]. There is no unencrypted mode.
config: both key_env_var and key_file are set — choose exactly one
Remove one of them.
environment variable LWS_BACKUP_KEY is not set (expected base64-encoded 32-byte key)
The configuration names an environment variable that is empty. Under systemd, check that EnvironmentFile= points at your key.env and that the file contains LWS_BACKUP_KEY= followed by the key. In a manual run, load it first, as shown in Verify and restore.
encryption key must decode to exactly 32 bytes, got ... or encryption key is not a valid base64 32-byte key
The key text is wrong: cut short, with extra characters, or not base64. A correct key is 44 characters ending in =. If this is your only key and backups already exist, find the original rather than making a new one: a new key cannot read old backups.
key file ... must not be group/world accessible (chmod 600 it)
The key file's permissions are too open. Run chmod 600 on it.
cannot parse config ...: ... (line N)
The configuration is not valid TOML. The message gives the line. Check quotes and section names.
config: retention_days must be in 1..3650, schedule_time must be HH:MM, and similar
A value is out of range. See the configuration reference.
Backup failures
Permission denied opening the database
The user running the backup needs write access to lock.mdb in the database folder, not only read access to data.mdb. LMDB records every reader in lock.mdb, even read-only ones. Run the backup as the database's own user (the supplied units use monero-lws), or put the backup user in the database's group and make lock.mdb group-writable.
Under systemd, the database folder must also be listed in BindPaths (or otherwise visible), and the destination and log in ReadWritePaths. See Adapt the service.
ambiguous LMDB layout: both .../lock.mdb and ...
The database folder has both lock.mdb and data.mdb-lock, so the tool cannot tell which one the running application uses. It refuses rather than risk an inconsistent copy. Find the lock file no process has open (for example with lsof), delete that one, and run again.
profile monero-lws but accounts table missing
profile is set to monero-lws, but the database has no monero-lws accounts table. Either db_path points at the wrong database, or this is not a monero-lws database: set profile = "generic" or "auto".
Verify fails for lack of memory
Verify decrypts the whole backup into RAM. Free some memory, or set [verify] scratch_dir to a folder on an encrypted volume. See Keys and security.
The walk stops and asks you to raise max_named_dbs
The database has more named tables than max_named_dbs (default 128). Raise it in [source], up to 4096.
removed stale partial file from an interrupted run
A warning, not an error. An earlier run stopped before finishing, and its encrypted .partial file was cleaned up. Your previous complete backups are untouched.
Verify and restore
decryption failed: wrong key or corrupted/tampered data
Either the key is not the one this backup was made with, or the file is damaged. Try the key from your off-server copy, and try an older backup. See When verify fails.
refusing to overwrite existing .../data.mdb
The restore target already holds a database. Choose an empty folder. The tool never overwrites one.
Questions
Does the backup slow down or lock my server?
No. It reads through an LMDB snapshot, which never blocks the writer. It opens the database read-only and never resizes it. The only side effect is that data.mdb may grow during a long backup, because LMDB cannot reuse freed pages while the snapshot is open; the space is reused afterwards.
Can I lose backups if backups stop for a while?
No. Retention always keeps the newest retention_days backups, however old they are, and runs only after a new backup has verified. See Retention.
Can a failed backup replace a good one?
No. A new file is only renamed into place after it has been decrypted, opened and fully read. Until then the previous files stay as they are.
Is it safe to copy backups to another server or cloud storage?
The .enc files are encrypted and authenticated, so yes, provided the key is not stored with them. Keep the key somewhere else entirely.
What happens if I lose the key?
Every backup made with it is permanently unreadable. There is no way around this. Keep a tested copy of the key off the server.
Does it work with databases other than monero-lws?
Yes, any LMDB environment. See Back up other LMDB databases.
Do I need to change anything when upgrading from 0.1?
No. The defaults reproduce the 0.1 behaviour: the same lws-backup- file names and the monero-lws checks through the auto profile. Old backups and manifests stay readable.
Where do I report a bug?
On the lmdb-lws-backup issues page. Include lmdb-lws-backup --version and the relevant log lines. Never post your key, key.env, or a restored database.