Diagnosing Timeshift Snapshot Failures on Linux Mint 21.x/22.x Cinnamon

The Problem

Timeshift on Linux Mint Cinnamon (21.x and 22.x) silently fails to create scheduled snapshots or produces a GRUB menu with no rollback entries after a broken update. You typically discover this when timeshift --list returns empty or the GRUB "Timeshift" submenu is missing entirely. The root cause is usually one of five configuration mismatches between your filesystem layout, Timeshift mode (BTRFS vs RSYNC), and the grub-btrfs integration.

Recognizable Condition

• Scheduled run logs show Snapshot creation failed or No space left on device in /var/log/timeshift/timeshift.log.
• Manual create with sudo timeshift --create exits non-zero but prints no actionable error.
• GRUB menu (hold Shift at boot) lacks a "Timeshift" entry, so you cannot roll back a bad kernel or package upgrade.
• GUI launches but shows zero snapshots despite Timeshift-Automatic being enabled in Update Manager.

Cause and Diagnostic Table

Symptom	Likely Cause	Log Evidence
"No space left on device" during create	Target partition full or disk_space_limit exceeded	timeshift.log shows ENOSPC on write
BTRFS mode: "Root subvolume not found"	Subvolume layout mismatch (missing @ or @home)	btrfs subvolume list / shows unexpected names
RSYNC mode: /home not snapshotted	exclude array in timeshift.json contains /home by default	Snapshot size far smaller than expected; /home absent in --list output
GRUB has no Timeshift submenu	grub-btrfs package missing or grub-btrfs.path not running	systemctl status grub-btrfs.path shows inactive/dead
RSYNC fails with permission denied on /home/user/.ecryptfs	Encrypted home (ecryptfs) blocks RSYNC read access	rsync exit code 23/24; timeshift.log shows Permission denied

Ordered Diagnostic Checks

Run each check in sequence. Stop when you identify the matching cause.

1. Inspect Timeshift's own health check and log

sudo timeshift --check
cat /var/log/timeshift/timeshift.log | tail -50

Where: Any terminal (user with sudo). Expected: --check prints a configuration summary and any immediate errors. The log shows the last run's rsync/btrfs output and exit codes.

2. Verify target mount and free space

BTRFS mode (root on BTRFS):

findmnt -T /timeshift
btrfs filesystem usage /timeshift

RSYNC mode (external drive at /timeshift):

df -h /timeshift
lsblk -f | grep timeshift

Risk: If the external drive is mounted at a different path (e.g., /media/user/backup), Timeshift will not find it. The backup_device_uuid in /etc/timeshift/timeshift.json must match the current mount.

3. Confirm BTRFS root subvolume layout

btrfs subvolume list /
# Look for lines ending with "@" and "@home"
# Example correct output:
# ID 256 gen 0 top level 5 path @
# ID 257 gen 0 top level 5 path @home

If you see @root, @mint, or no @ at all, Timeshift cannot locate the root subvolume. This happens when the installer created a non-standard layout or you migrated from ext4 without recreating subvolumes.

4. Check grub-btrfs service and GRUB hook

systemctl status grub-btrfs.path
ls -l /etc/grub.d/41_snapshots_btrfs

Expected: Service active (waiting); hook file exists and is executable (-rwxr-xr-x). If missing, grub-btrfs is not installed or the hook was not generated.

5. Examine Timeshift configuration for excludes and device UUID

cat /etc/timeshift/timeshift.json | jq .
# Or without jq:
sudo grep -A2 -B2 'exclude\|backup_device_uuid' /etc/timeshift/timeshift.json

Key fields: exclude (array), backup_device_uuid (string), mode ("BTRFS" or "RSYNC"). RSYNC mode defaults to excluding /home, /root, /mnt, /media, /tmp, /var/tmp, /swapfile, /lost+found.

Fixes Tied to Findings

Insufficient space on target

BTRFS: Run btrfs balance start -dusage=10 /timeshift to reclaim unallocated chunks, or delete old snapshots with sudo timeshift --delete --snapshot '2024-01-15_10-30-00'. Add a safety margin in config:

sudo sed -i 's/"disk_space_limit": 0/"disk_space_limit": 10/' /etc/timeshift/timeshift.json
# 10 = keep 10% free; adjust per disk size

RSYNC: Ensure the external drive is ext4 (not NTFS/FAT32). NTFS loses POSIX permissions and breaks restores. Reformat if needed: sudo mkfs.ext4 -L timeshift /dev/sdX1, then update backup_device_uuid in the JSON config.

BTRFS subvolume layout mismatch

If btrfs subvolume list / shows no @, recreate snapshots targeting the correct subvolume:

sudo timeshift --create --btrfs-subvolume @ --comments "fixed-layout"
# Verify:
sudo timeshift --list | grep fixed-layout

If the root subvolume is named differently (e.g., @mint), edit /etc/timeshift/timeshift.json and set "btrfs_subvolume": "@mint". Then re-run --create.

RSYNC excludes /home unintentionally

Edit the exclude array to remove /home (or the specific user directories you want backed up):

sudo cp /etc/timeshift/timeshift.json /etc/timeshift/timeshift.json.bak
sudo jq '.exclude |= map(select(. != "/home"))' /etc/timeshift/timeshift.json > /tmp/ts.json && sudo mv /tmp/ts.json /etc/timeshift/timeshift.json

Verify: sudo timeshift --create --comments "with-home" && sudo timeshift --list | grep with-home. Snapshot size should increase by roughly the size of /home.

Missing or inactive grub-btrfs

sudo apt update && sudo apt install grub-btrfs
sudo systemctl enable --now grub-btrfs.path
sudo update-grub

Reboot and hold Shift. The GRUB menu should now show a "Timeshift" submenu with snapshot entries. Each entry boots a read-only root snapshot via the kernel parameter rootflags=subvol=@timeshift-btrfs/snapshots/....

Encrypted home (ecryptfs) blocking RSYNC

ecryptfs is deprecated in Mint 21+. Migration path:

1. Back up /home to an external ext4 drive (rsync -aHX --info=progress2).
2. Reinstall Mint with LUKS2 full-disk encryption (installer option).
3. Restore /home from the backup.

Alternative (no reinstall): Use BTRFS snapshots on a BTRFS root with an unencrypted /home subvolume (@home). Timeshift BTRFS mode snapshots the entire filesystem, including @home, atomically.

Escalation Criteria

Escalate to the Linux Mint forums (forums.linuxmint.com) or Timeshift GitHub issues when:

• BTRFS corruption: sudo btrfsck --check-data-csum /dev/sdX reports uncorrectable errors. Do not attempt repair without a backup.
• GRUB entry missing after reinstall: grub-btrfs installed and update-grub run, but grep -r timeshift /boot/grub/grub.cfg returns nothing.
• RSYNC exit 23/24 persists: Permissions fixed and excludes cleaned, but rsync still fails on specific files (often ~/.cache or FUSE mounts).
• GUI segfault: timeshift-gtk crashes on launch; dmesg | grep timeshift shows segfault in libgtk-3.so. This is a packaging bug.

Practical Verification After Fix

1. Create a test snapshot: sudo timeshift --create --comments 'verify-$(date +%F)'
2. List and confirm: sudo timeshift --list | grep verify — should show the new snapshot with size greater than 0.
3. GRUB menu check: Reboot, hold Shift, navigate to the "Timeshift" submenu. The new snapshot should appear. Press 'e' on the entry; the kernel line must contain rootflags=subvol=@timeshift-btrfs/snapshots/... (BTRFS) or an equivalent overlay parameter (RSYNC).
4. Full restore test (non-destructive): Use a VM or spare partition. Identify the target device (e.g., /dev/sdb2). Run:

   sudo timeshift --restore --snapshot '2024-10-12_14-30-00' --target /dev/sdb2 --skip-grub

   Mount the restored partition and verify key files: ls /mnt/@/etc/hostname, ls /mnt/@home/user/Documents.

Limitations and Version Notes

• Timeshift 23.x/24.x (Mint 21/22 defaults). Flag syntax may differ in older 20.x releases.
• BTRFS mode requires /boot on the same BTRFS filesystem. A separate /boot partition (ext4) breaks grub-btrfs submenu generation.
• Kernel updates via Update Manager only trigger automatic snapshots if Timeshift-Automatic is checked in Update Manager → Preferences → Automation.
• External RSYNC drives must stay mounted at the same path (/timeshift) with the same UUID. A udev rule or /etc/fstab entry is recommended.
• This guide covers the Cinnamon edition; Xfce/MATE editions use the same Timeshift backend but may have different default timeshift.json values.

Quick Reference Commands

Task	Command
Check Timeshift version	timeshift --version
List BTRFS subvolumes	btrfs subvolume list /
Show GRUB snapshot entries	grep -A2 'Timeshift' /boot/grub/grub.cfg
Delete oldest snapshot	sudo timeshift --delete --snapshot $(sudo timeshift --list | awk '/^[0-9]/ {print $1; exit}')
View Mint-specific docs	cat /usr/share/doc/timeshift/README.mint