Raspberry Pi OverlayFS: Changes Lost After Reboot and Update Problems

If packages, configuration edits, or browser settings disappear after reboot, check whether Raspberry Pi OS is using a temporary OverlayFS root. A successful write to / can be stored in RAM while the underlying filesystem remains unchanged. This guide distinguishes that expected reset behaviour from read-only mount errors and failed storage.

Match the OverlayFS symptom

Symptom	First check	Meaning to investigate
Edits work but vanish at reboot	Actual root mount and upper layer	Temporary overlay discards runtime changes
/boot/firmware rejects writes	Boot partition mount options	Boot protection is separate from root overlay
APT reports success but packages disappear	Whether updates ran inside the overlay	Changes were not committed to persistent root
Read-only file system appears unexpectedly	Mount options and kernel errors	Intended protection or storage/filesystem fault
No space left on device despite free SD space	Upper-layer capacity, inodes, RAM	The limiting filesystem may be temporary
Disabling boot protection fails while overlay is active	Current root mode and pending reboot	Finish disabling root overlay first

1. Inspect the actual mount for each affected path

# Read-only inspection: root, home, boot, and any overlay mounts.
cat /etc/os-release
findmnt -T / -o TARGET,SOURCE,FSTYPE,OPTIONS
findmnt -T /home -o TARGET,SOURCE,FSTYPE,OPTIONS
findmnt -T /boot/firmware -o TARGET,SOURCE,FSTYPE,OPTIONS
findmnt -t overlay
cat /proc/cmdline

Use findmnt -T with the exact application data path too. A directory named /data is not persistent simply because of its name: if no separate filesystem is mounted there, it is part of the overlaid root. Docker volumes and bind mounts likewise persist only when their underlying host storage persists.

In the current Trixie raspi-config implementation, the temporary-root setting uses overlayroot=tmpfs. Custom images and older releases can use different mechanisms. Mount output establishes the current filesystem; a saved configuration describes what a later boot may use.

Compare current and configured state on Trixie

# These installed raspi-config queries print 0 when detected, 1 otherwise.
sudo raspi-config nonint get_overlay_now
sudo raspi-config nonint get_overlay_conf
sudo raspi-config nonint get_bootro_now
sudo raspi-config nonint get_bootro_conf

These are setting queries, not filesystem health checks. Verify their presence in your installed package as explained in the raspi-config diagnosis guide. A pending reboot can explain a difference between configured and current state.

2. Save needed runtime changes before rebooting

Disabling the overlay and rebooting discards its temporary changes. Before doing so, export application configuration and back up data to verified persistent storage or another computer. A backup stored elsewhere under the same temporary root will disappear too.

Keep application-consistent database backups rather than copying an actively written database directory. Include credentials, SSH configuration, device identity, and any changes needed to reconnect remotely. Check that the destination filesystem is mounted and writable, then inspect the exported files.

3. Disable root OverlayFS and reboot first

Open the supported configuration tool:

sudo raspi-config

Use Performance Options → Overlay File System to disable the root overlay. Reboot with local recovery access available. On Trixie, changing boot-partition protection while the root overlay is still active can be refused because the permanent fstab change cannot be made in that state.

After reboot, check the actual mounts again. If boot write protection also needs to be removed for maintenance, return to the menu now, make that change, and reboot when requested. Follow this sequence rather than repeatedly changing both settings inside a temporary root.

# Check that maintenance is taking place on the intended persistent filesystem.
findmnt -T / -o TARGET,SOURCE,FSTYPE,OPTIONS
findmnt -T /boot/firmware -o TARGET,SOURCE,FSTYPE,OPTIONS

Do not assume a menu confirmation means the running root has already changed. Also, mount -o remount,rw / does not turn a RAM-backed overlay into persistent storage or commit its contents to the lower layer.

4. Update and verify while the temporary overlay is disabled

Once the persistent root and required boot partition are writable, apply updates within the same Raspberry Pi OS release:

sudo apt update
sudo apt full-upgrade
systemctl --failed

Read APT's proposed changes and errors. If an interrupted installation remains after returning to the persistent root, use the APT diagnosis guide rather than deleting package locks or assuming an overlay error explains every package failure.

Reboot with the overlay still disabled, verify package versions and application behaviour, and restore the exported changes as needed. Re-enable the overlay only after the persistent baseline works. Then reboot again and test both disposable changes and required persistent state.

5. Make application persistence explicit

For an appliance that must retain data, use a separately mounted writable filesystem and configure the application to store its state there. Verify the mount before starting the writer; otherwise a missing data device can cause writes to land in a plain directory on the temporary root.

For your own systemd service, a mount dependency can help:

# Add to the [Unit] section of your application's service or its drop-in.
[Unit]
RequiresMountsFor=/srv/pi-data

This adds ordering and requirements for mounts needed to access the path. It does not create a separate mount or prove that /srv/pi-data is on the intended device. Configure the mount, inspect findmnt -T /srv/pi-data, and test the service with the device present and absent. See the systemd unit dependency reference for Trixie.

6. Distinguish full temporary storage from a read-only fault

# Inspect capacity, inode usage, memory pressure, and kernel evidence.
df -hT
df -i
free -h
cat /proc/pressure/memory
sudo journalctl -k -b --no-pager | grep -Ei 'mmc|nvme|I/O error|EXT4-fs|read-only|oom|out of memory'

For a temporary overlay, inspect the upperdir shown in mount options and the filesystem backing it; free space on the SD card alone is not enough. Relocate or bound the writer that grows logs, downloads, caches, or application data. See the memory-pressure guide.

If an ordinary persistent root unexpectedly became read-only alongside I/O or filesystem errors, preserve data and investigate storage and power. Do not repeatedly force a writable remount. Filesystem repair should use recovery media with the affected filesystem unmounted.

Persistence test after maintenance

Use harmless markers in a test location, not production database files:

1. With overlay disabled, confirm that an intended persistent test file survives reboot.
2. Re-enable the temporary overlay and confirm that a disposable root test file disappears.
3. Confirm that data on the separately mounted filesystem still survives.
4. Test startup with the data device missing so the application does not silently write to temporary root.
5. Repeat the documented maintenance procedure before relying on remote-only updates.

For a complete setup and rollback plan, see the OverlayFS read-only-root guide.

References and related guides

• Trixie raspi-config implementation — current and configured checks, temporary-root switch, and boot-protection sequence.
• Linux kernel OverlayFS documentation — upper/lower layer behaviour and mount requirements.
• Reduce SD-card writes
• Sudo and administrator access

Implementation checked on 3 October 2026. This maintenance procedure needs validation on your image and data layout; it does not claim that every custom overlay uses temporary RAM storage.