Updated: October 11, 2026

UniFi UNAS-Pro Snapshot Issues#

The August 2, 2026 emergency pool migration copied nine shared drives into ordinary directories instead of Btrfs subvolumes. File access worked, but snapshots and quota operations failed. The repair is to replace each affected share root with a Btrfs subvolume and ensure its separate snapshot destination exists. GoogleCloudSync, Documents, Immich, Books, HomesDSM, Musique, Nadine, and Software were repaired on October 10, 2026. Photos was repaired on October 11, 2026.

Plain-language explanation and next-move guide#

What happened#

On August 2, the files were copied to the new pool, but the destination shares were not set up in the format UniFi Drive needs for snapshots. People could still open and save files, so the shares looked healthy. Snapshot and quota jobs failed because the NAS expected each share to be created as a managed share, not just as a folder containing the right files.

Think of it like moving everything into a room but leaving out the filing system the NAS uses to make restore points. A normal file copy or folder rename cannot add that structure afterward. The destination has to be created correctly first, and then the files copied into it. That copy may take hours for a large share. The quick rename at the end only switches the already prepared destination into place.

The next time a shared folder needs to move to another pool#

Use this workflow for a replacement share. Keep the old share and its files until the new one has passed the checks below.

1. Decide whether the share must keep its existing identity. If its current name, users, backup jobs, and app connections must continue unchanged—or if old snapshots must be preserved—do not create a replacement or manually change NAS records. First confirm a UniFi-supported migration method for the installed version. The ordinary file-copy method below creates a new share identity, and old snapshots do not come along with the files.
2. Prepare the move. Confirm there is a separate backup and enough room for both copies. Write down who and what uses the share: people, computers, sync jobs, backup jobs, permissions, quotas, and snapshot schedule. Choose a maintenance window and pause anything that can write to the old share for the final copy.
3. Create the destination in UniFi Drive on the new pool. Give it a temporary, distinct name. Set its users and access, then create a small test snapshot and make sure it can be opened. This confirms the NAS prepared the destination correctly before any data is moved.
4. Copy the user files into the destination share. Use the normal file-sharing interface or a supported migration tool. Copy the contents, not the old share’s hidden NAS-managed folders. For a large share, an initial copy can run while people continue working; pause writers for a final catch-up copy.
5. Check the new copy and snapshot. Compare the old and new file lists and sizes; check representative important files, and use a full content comparison when the data warrants it. Create and browse another snapshot of the populated destination. Open files from a normal client and confirm required backup access still works.
6. Switch users and jobs to the new share. Update computers, sync tasks, backup jobs, and any applications that refer to the old name or location. Resume writers only after they point to the new share.
7. Keep the old share until the new one proves itself. Wait for at least one scheduled snapshot and one relevant backup to succeed. Then handle the old share and its snapshots according to the retention plan; do not delete them as part of the move itself.

If the same share identity or its snapshot history must be retained, stop before step 3 and use a specifically supported migration plan. A regular file copy transfers files, not the NAS share identity or its historical snapshots.

1. Host, symptoms, and cause#

Snapshots stopped working after the emergency move from Pool 1 to Pool 2 on August 2. Restarting the NAS, replacing schedules, and attempting manual snapshots did not fix the problem. The October 10 Documents schedule did execute at 07:45 EDT, although the UI showed no event; its failure was recorded in the udcd journal.

2026-10-10T07:45:00-0400
OP_DRIVE_SNAPSHOT_TAKE: /volume/6e27154a-8dc4-47dc-ad96-befb70ec47e9/.srv/.unifi-drive/Documents: ERROR: Not a Btrfs subvolume: Invalid argument

Boot-time quota operations reported the same condition:

OP_DRIVE_QUOTA_SET: .../.unifi-drive/GoogleCloudSync:
ERROR: Not a Btrfs subvolume: Invalid argument

The August 2 migration record describes copying share roots with rsync -aHAXS, updating shared_drives.storage_pool_id, and restarting services. It does not include creating destination subvolumes. Rsync copied the files and metadata, but did not reproduce the source roots’ Btrfs subvolume identity. Updating the database changed the application paths without provisioning the required filesystem structure.

The affected-share list exactly matches that migration. Documents and GoogleCloudSync also have destination-folder birth timestamps from August 2. This strongly supports the migration as the cause; August logs were no longer retained, so the historical sequence is inferred from the migration record and current metadata.

Investigation evidence and limits#

The initial SSH investigation on October 10, 2026, around 07:49 EDT was read-only. Direct btrfs subvolume show checks confirmed the affected roots were ordinary directories. No NAS files, settings, services, or schedules were changed until the user approved the GoogleCloudSync pilot after confirming backups and paused writers/jobs.

• Documents snapshot failures were recorded at 07:31:38, 07:40:02, 07:40:24, 07:41:54, and 07:45:00 EDT.
• During boot, 07:34:11–07:34:13 EDT, quota operations reported the same subvolume error for all nine affected shares.
• Journal entries appeared twice through different logging paths; these duplicates were not separate snapshot attempts.
• The retained journal began October 9, 2026 at 21:22:11 EDT. August 2 logs were unavailable. The October 10 boot began at 07:33:19 EDT.

Folder metadata captured before repair:

Storage and service checks at diagnosis:

• Pool 2 was mounted read-write as Btrfs.
• Data RAID5 array md3 had 4/4 disks online ([UUUU]).
• Estimated/statfs free space was 10.53 TiB.
• Btrfs device counters were zero for write, read, flush, corruption, and generation errors.
• No failed systemd units were reported; unifi-drive, udcd, and usd were active.

Those checks found no capacity or recorded device-error explanation for the snapshot failure; they were not a complete disk-health audit.

Share status after the Software repair#

2. Required on-disk layout#

Two separate structures are required for the tested UniFi Drive configuration:

.unifi-drive/
├── GoogleCloudSync/                       Btrfs subvolume — live share root
│   ├── .data/                             User files; rsync exports this directory
│   ├── .trashcan/
│   └── .uploads/
└── .snapshot/                            Ordinary directory
    └── GoogleCloudSync/                  Ordinary directory — snapshot destination
        └── <snapshot UUID>/              Read-only Btrfs snapshot subvolume

The live share root must be a subvolume. Its .snapshot/<share> container is a separate ordinary directory and is not included when copying the live root. A Btrfs snapshot requires a subvolume source; being located on a Btrfs filesystem alone is insufficient. Btrfs subvolume documentation.

After fixing GoogleCloudSync’s live root, manual attempts at 08:03:25 and 08:04:05 EDT on October 10 exposed the second missing structure:

OP_DRIVE_SNAPSHOT_TAKE: .../.unifi-drive/GoogleCloudSync:
ERROR: cannot access '.../.unifi-drive/.snapshot/GoogleCloudSync': No such file or directory

Creating that destination with the ownership and permissions used by .snapshot/Downloads resolved this failure. That additional directory creation required no service interruption.

3. Repair procedure for an existing affected share#

This is a maintenance procedure, not an automatic script. Verify an independent backup and obtain explicit approval for filesystem/service changes under AGENTS. Repair one share at a time. Do not rerun the repair on GoogleCloudSync: it is already fixed.

A. Inspect and prepare#

1. Identify the target share and confirm its actual UniFi storage-pool mapping.
2. Verify a current independent backup and enough space for the replacement and retained original.
3. Record root ownership/mode, quota, SMB/NFS configuration, rsync export, snapshot schedule, and service states.
4. Identify active clients and pause all writers, sync tools, and backup jobs using the share. SMB/NFS shutdown does not stop direct SSH/rsync access or local processes.
5. Choose unused staging and rollback paths; inspect their containing subvolumes before deciding how the switch will work.

Run examples in a single Bash session on the NAS after setting the correct share name:

POOL='/volume/6e27154a-8dc4-47dc-ad96-befb70ec47e9'
DRIVE_ROOT="$POOL/.srv/.unifi-drive"
SHARE='CHANGE_ME'
STAMP=$(date +%Y%m%d-%H%M%S)

case "$SHARE" in
  ''|CHANGE_ME|*/*|.*) echo 'Set one valid existing share name first'; exit 1 ;;
esac

LIVE="$DRIVE_ROOT/$SHARE"
STAGE="$POOL/.srv/repair-$SHARE-$STAMP"
ROLLBACK="$POOL/.srv/original-$SHARE-$STAMP"
SNAP_DEST="$DRIVE_ROOT/.snapshot/$SHARE"

test -d "$LIVE" && test ! -L "$LIVE" || exit 1
test ! -e "$STAGE" && test ! -L "$STAGE" || exit 1
test ! -e "$ROLLBACK" && test ! -L "$ROLLBACK" || exit 1

if btrfs subvolume show "$LIVE" >/dev/null 2>&1; then
  echo 'Already a subvolume; inspect the actual error instead of replacing it'
  exit 1
fi

du -sh "$LIVE"
stat -c '%n | mode=%a uid=%u gid=%g inode=%i' "$LIVE"
btrfs inspect-internal rootid "$DRIVE_ROOT"
btrfs inspect-internal rootid "$POOL/.srv"
systemctl is-active unifi-drive udcd smbd nfs-server

In the pilot, .unifi-drive belonged to subvolume 258, while .srv belonged to 257. Moving the original ordinary directory into .srv made GNU mv copy the data and then remove the old instance; it was not an instant rename. The retained original was subsequently verified by checksum. Do not assume this rollback move is quick for Photos or other large shares. For a large repair, plan an unexported rollback holding location within the same containing subvolume as the live ordinary directory, verify the boundary, and confirm the application will leave that holding location alone. Do not put rollback data inside any exported .data tree.

B. Create and populate the replacement#

btrfs subvolume create "$STAGE"
rsync -aHAXS --numeric-ids --stats "$LIVE/" "$STAGE/"
btrfs subvolume show "$STAGE"
stat -c '%n | mode=%a uid=%u gid=%g' "$LIVE" "$STAGE"

Copy the entire share root, including .data, .trashcan, .uploads, and other hidden entries. Preserve root attributes as well as file attributes. -aHAXS --numeric-ids preserves the metadata used in the pilot, including supported ACLs and extended attributes; it does not create a subvolume by itself. Rsync manual.

C. Prepare the snapshot destination#

Inspect a working destination on the same pool, such as .snapshot/Downloads. In the pilot, these containers were ordinary directories, mode 770, UID/GID 988:988 (unifi-drive). Use the actual local reference rather than assuming those numeric IDs on a different NAS.

REFERENCE="$DRIVE_ROOT/.snapshot/Downloads"
test -d "$REFERENCE" || exit 1

if [ ! -e "$SNAP_DEST" ] && [ ! -L "$SNAP_DEST" ]; then
  mkdir -m 770 "$SNAP_DEST"
  chown --reference="$REFERENCE" "$SNAP_DEST"
  chmod --reference="$REFERENCE" "$SNAP_DEST"
fi

test -d "$SNAP_DEST" && test ! -L "$SNAP_DEST" || exit 1
stat -c '%n | mode=%a uid=%u gid=%g' "$REFERENCE" "$SNAP_DEST"

If an existing destination contains snapshots, retain it and inspect its permissions; do not overwrite or empty it. If the pool’s .snapshot parent or a known working reference is absent, stop and resolve provisioning instead of guessing its layout.

D. Final synchronization and switch#

The pilot temporarily stopped unifi-drive, udcd, smbd, and nfs-server. This interrupts access to other shares through the affected services. Record which services were active and restore only the services that were active before maintenance. Keep usd and SSH running; neither was stopped in the pilot.

In the approved Bash maintenance session, record the active services and install a restoration trap before stopping them:

ACTIVE_SERVICES=()
for service in udcd unifi-drive nfs-server smbd; do
  if systemctl is-active --quiet "$service"; then
    ACTIVE_SERVICES+=("$service")
  fi
done

restore_services() {
  if [ "${#ACTIVE_SERVICES[@]}" -gt 0 ]; then
    systemctl start "${ACTIVE_SERVICES[@]}"
  fi
}
trap restore_services EXIT

if [ "${#ACTIVE_SERVICES[@]}" -gt 0 ]; then
  systemctl stop "${ACTIVE_SERVICES[@]}" || exit 1
fi
for service in udcd unifi-drive nfs-server smbd; do
  if systemctl is-active --quiet "$service"; then
    echo "Service still active: $service; do not switch paths"
    exit 1
  fi
done

1. Stop the approved services and verify they are inactive.
2. Perform a final checksum synchronization from live to staging.
3. Run an independent checksum/metadata comparison, checking for extra destination files too.
4. Proceed only when comparison output is empty and the command succeeds.

rsync -aHAXS --numeric-ids --checksum --stats "$LIVE/" "$STAGE/"
rsync -aHAXS --numeric-ids --checksum --dry-run --itemize-changes \
  --delete "$LIVE/" "$STAGE/"

Here --delete is used only with --dry-run, to report extra staging files without deleting them. If differences remain, investigate and correct the staging copy before switching. Do not blindly apply a deletion pass.

After successful validation, retain the original and put the replacement at the exact existing live path:

test ! -e "$ROLLBACK" && test ! -L "$ROLLBACK" || exit 1
btrfs subvolume show "$STAGE" >/dev/null || exit 1

mv -T "$LIVE" "$ROLLBACK" || exit 1
if ! mv -T "$STAGE" "$LIVE"; then
  echo 'Replacement move failed; attempt to restore the original path'
  mv -T "$ROLLBACK" "$LIVE"
  exit 1
fi

sync -f "$LIVE"
btrfs subvolume show "$LIVE"
stat -c '%n | mode=%a uid=%u gid=%g inode=%i' "$LIVE" "$ROLLBACK"

Restore the recorded services after the successful switch:

restore_services || exit 1
for service in "${ACTIVE_SERVICES[@]}"; do
  systemctl is-active "$service" || exit 1
done
trap - EXIT

The EXIT trap is a fallback for command failures; it is not a substitute for inspecting both paths after a failed move or recovery from a killed/lost session. The existing UniFi share ID, storage-pool ID, and share name were retained; no database edits were needed for this same-pool repair.

E. Restart and validate before resuming writers#

1. Restart the previously active services; verify their states and logs.
2. Compare the retained original against the new live share using the same checksum/metadata dry-run. Investigate any differences before accepting the repair.
3. Verify the new quota group and its limits agree with the UniFi quota setting.
4. In UniFi Drive, create a manual snapshot, browse its contents, and check the result in logs/application records.
5. Confirm that the new snapshot is a read-only subvolume and its parent UUID matches the live share UUID.
6. Reconnect SMB/NFS clients as necessary; open representative existing files.
7. Confirm the rsync module still points to .../<share>/.data and list it with a GNU rsync client using the existing backup authentication.
8. Resume paused writers and backup jobs after acceptance. Check the next scheduled snapshot and backup execution separately.

Useful read-only checks:

journalctl -u udcd -u unifi-drive --since '15 minutes ago' --no-pager
btrfs subvolume show "$LIVE"
btrfs qgroup show -reF "$LIVE"

# Use the actual new snapshot UUID from UniFi/Btrfs metadata.
btrfs subvolume show "$SNAP_DEST/<snapshot UUID>"
btrfs property get -ts "$SNAP_DEST/<snapshot UUID>" ro

# From a GNU rsync client with the existing SSH authentication:
rsync --list-only -e ssh "root@10.1.2.2::$SHARE/"

F. Rollback and cleanup#

Retain the original until the repair and normal scheduled runs have been accepted. Before writers resume, rollback consists of stopping the same services, moving the replacement aside, restoring the retained original to the original path, and restarting services. This returns to the former snapshot limitation.

After writers resume, compare and reconcile new writes first: simply restoring the older directory could omit new or changed files. Removal of retained originals, test data, or snapshots is a separate explicitly approved cleanup operation.

4. GoogleCloudSync pilot: actual result#

Actual staging location used for the replacement, created at 07:57:27 EDT and moved into the original live path during cutover:

/volume/6e27154a-8dc4-47dc-ad96-befb70ec47e9/.srv/repair-googlecloudsync-20261010

Retained rollback location:

/volume/6e27154a-8dc4-47dc-ad96-befb70ec47e9/.srv/original-googlecloudsync-20261010

The retained original is a full ordinary-directory copy. Its inode changed from 69946 to 4972 when GNU mv crossed from containing subvolume 258 to 257. Its contents and metadata were verified against the repaired live share after cutover. The replacement retained Btrfs subvolume ID 26940 when moved into .unifi-drive.

Verified new snapshot location:

/volume/6e27154a-8dc4-47dc-ad96-befb70ec47e9/.srv/.unifi-drive/.snapshot/GoogleCloudSync/c275bef3-2b99-42a3-82d0-361c8121a87d

UniFi’s shared_drive_snapshot_runs recorded the manual test as succeeded, with no error codes. UI testing was performed by the user; browser computer access was unavailable to the agent. The user confirmed snapshot contents and Mac SMB file access, then was informed that paused sync/backup jobs could resume. The agent did not restart externally paused jobs or alter snapshot schedules. A subsequent scheduled snapshot execution had not yet been tested.

The 26 historical snapshot records remained through cutover. The user subsequently deleted the old snapshots in the UI; the count was zero before the successful new test. Historical snapshot contents were not verified before deletion. The repair made no direct snapshot deletions or database changes. It does not recover historical snapshots lost or left behind during the earlier migration.

Rsync backup settings were preserved#

The GoogleCloudSync rsync module remains exported through /etc/rsyncd.conf at:

[GoogleCloudSync]
    path = /volume/6e27154a-8dc4-47dc-ad96-befb70ec47e9/.srv/.unifi-drive/GoogleCloudSync/.data

The exported .data directory retained mode 770, UID/GID 988:988. A NAS-side GNU rsync listing in the stdio daemon mode used for SSH backups succeeded. The backup scripts do not need a path change. Full TrueNAS backup runs were not triggered during this verification.

The Mac’s built-in openrsync encountered a protocol mismatch during the initial listing attempt; that was not evidence of a missing module. Use a compatible GNU rsync client for this check. The deployment uses rsync daemon mode over SSH; a listening TCP 873 service is not required for that transport.

See Unifi UNAS-Pro Backup Strategy for the fleet’s existing pull jobs and authentication setup. Do not change credentials or backup schedules as part of this filesystem repair.

5. Documents pilot repair — October 10, 2026#

The user explicitly requested this repair. Six SMB clients were connected during preflight, so the replacement was staged while the original share remained online, followed by a brief file-services interruption for the final sync and switch.

The staging subvolume was created at:

/volume/6e27154a-8dc4-47dc-ad96-befb70ec47e9/.srv/repair-Documents-20261010-0817

The original is retained at a hidden rollback path in the same containing subvolume, allowing a fast rename without copying another 24 GB:

/volume/6e27154a-8dc4-47dc-ad96-befb70ec47e9/.srv/.unifi-drive/.repair-rollback-Documents-20261010-0817/Documents

All four file services (unifi-drive, udcd, smbd, nfs-server) were confirmed active after the switch. UniFi regenerated the Documents Samba share. The snapshot schedule was not changed. A manual UI snapshot and client access were not tested during this repair; the next scheduled run has not yet been checked. The user requested that no unnecessary tests be run, so this record claims the verified filesystem repair without claiming that a Documents snapshot succeeded.

6. Immich repair — October 10, 2026#

The user requested the same repair for Immich. Six SMB clients were connected during preflight. The 33 GB share was staged while online, then checksum-compared during a brief file-services interruption before switching paths.

The staging subvolume is:

/volume/6e27154a-8dc4-47dc-ad96-befb70ec47e9/.srv/repair-Immich-20261010-0835

The original is retained for rollback at:

/volume/6e27154a-8dc4-47dc-ad96-befb70ec47e9/.srv/.unifi-drive/.repair-rollback-Immich-20261010-0835/Immich

All four file services (unifi-drive, udcd, smbd, nfs-server) were confirmed active after the switch. The existing rsync module still points to .../.unifi-drive/Immich/.data; the UniFi share ID, pool, quota, and snapshot schedule were unchanged. A manual UI snapshot and client file access were not tested during this repair; the next scheduled run has not yet been checked.

7. Additional share repairs — October 10, 2026#

The user requested these shares one at a time, excluding Photos. Each live root was replaced with the staged Btrfs subvolume at the original path. The original directory was retained at its listed rollback location. No share database edits or schedule changes were made.

All five shares remain on Pool 2. Their live roots are mode 750, UID/GID 988:988. The four file services (udcd, unifi-drive, nfs-server, smbd) were active after each repair. These repairs restored the filesystem structure and snapshot destinations; manual UniFi UI snapshots were not run for these five shares, so snapshot creation is not claimed as tested.

The Software share contained 22,217 regular files and 4,133 directories, totaling 317,904,992,215 bytes. The completed checksum sync updated three files (174,049 bytes); the final sync while services were stopped transferred zero files. The final dry run found no source-side updates. Three older files present in staging but absent from the original live folder were deliberately preserved at the user’s direction:

.data/PVEBackups/HP4PVEBackup/2026-10-03_13-15-01_HP4Backup.tar.zst.sha256
.data/PVEBackups/HP4PVEBackup/2026-10-03_13-15-01_HP4Backup.tar.zst
.data/PVEBackups/HP4PVEBackup/2026-10-03_13-15-01_Backup.log

Software’s existing rsync module remains in /etc/rsyncd.conf at .../.unifi-drive/Software/.data. Its existing schedule, share ID, pool, and unlimited quota were not altered.

Rollback locations:

Books:    /volume/6e27154a-8dc4-47dc-ad96-befb70ec47e9/.srv/.unifi-drive/.repair-rollback-Books-20261010-0905/Books
HomesDSM: /volume/6e27154a-8dc4-47dc-ad96-befb70ec47e9/.srv/.unifi-drive/.repair-rollback-HomesDSM-20261010-0930/HomesDSM
Musique:  /volume/6e27154a-8dc4-47dc-ad96-befb70ec47e9/.srv/.unifi-drive/.repair-rollback-Musique-20261010-0936/Musique
Nadine:   /volume/6e27154a-8dc4-47dc-ad96-befb70ec47e9/.srv/.unifi-drive/.repair-rollback-Nadine-20261010-1035/Nadine
Software: /volume/6e27154a-8dc4-47dc-ad96-befb70ec47e9/.srv/.unifi-drive/.repair-rollback-Software-20261010-1041/Software

The Software repair left the three preserved extras in the new live share and kept its former live folder at the rollback location. No snapshot or source files were deleted.

8. Photos repair — October 11, 2026#

Photos was migrated to a Btrfs subvolume on Pool 2. The live share root is subvolume 26950, UUID 973eb42e-2fbb-dc4e-9438-8b55b85a6eed, mode 750, UID/GID 988:988. The separate snapshot container .snapshot/Photos was created with mode 770, UID/GID 988:988, matching .snapshot/Downloads.

Before switching, the full tree had 61,056 regular files and 1,880,316,737,274 bytes. An rsync dry run comparing the full tree’s names, sizes, timestamps, and preserved metadata reported no differences; the final sync while file services were stopped transferred zero files. Seven small folders were independently checksum-compared with no differences: 2013-04-27 Boston, 2019-06-24 Ogunquit, 2023-12-06 90 de la Bourgade en hiver, 2024-04-08 Éclipse Solaire, 2024-06-03 Lake of the Clouds Hike, 2024-07-29 Rivière Ouelle - Fredericton, and 2024-08-20 Miscou Island. A full content checksum of all 1.87 TB was not run.

The former live directory remains at:

/volume/6e27154a-8dc4-47dc-ad96-befb70ec47e9/.srv/.unifi-drive/.repair-rollback-Photos-20261010-2129/Photos

The Photos rsync module still points to .../.unifi-drive/Photos/.data. The share configuration and snapshot schedule were not edited. All four file services (udcd, unifi-drive, nfs-server, smbd) were active after the switch. A manual UniFi snapshot and client access were not tested after repair.

9. Moving data between pools in the future#

Preferred: provision the destination through UniFi#

1. Verify an independent backup, destination capacity, and an agreed maintenance window. Record share permissions, quotas, exports, schedules, and consumers.
2. Use a vendor-supported migration workflow if the installed UniFi version explicitly provides one. Otherwise, create a new destination shared drive through UniFi Drive, with a distinct name on the intended pool. Ubiquiti documents shared-drive creation under UniFi Drive → All Files → New Shared Drive; this is not a documented repair/conversion button. Ubiquiti shared-drive creation guide.
3. Before copying data, confirm the actual destination share root is a Btrfs subvolume and its .snapshot/<destination share> container exists with correct permissions. Set user access, quotas, and required SMB/NFS/rsync exports in the application.
4. Copy user content into the newly provisioned share’s .data directory or through its normal file-access interface. Do not replace the provisioned root with an ordinary directory. For an application-managed new share, do not blindly copy the old root’s internal state over the newly provisioned structure.
5. Pause source writers and dependent jobs for final synchronization. Compare file contents and the metadata required by the workload, then test a destination snapshot and file access.
6. Cut clients and backup jobs over to the new share using supported application configuration. A newly created share has a different application identity; reproduce permissions/settings and update consumers where necessary. Renaming or relocating it requires rechecking actual paths and exports.
7. Verify the next scheduled snapshot and backup runs. Retain the old source until the destination has been accepted; do not destroy a failing source pool merely because file access works on the new pool.

Controlled manual migration when application identity must be retained#

A same-pool repair preserves identity by retaining the exact live path. A cross-pool move also changes application storage references and is a separate migration procedure requiring review.

For a manual full-root transfer, explicitly create the destination Btrfs subvolume before copying into it, preserve the entire root and metadata, provision the separate snapshot destination, and reconcile application configuration only after validation. A PostgreSQL storage_pool_id update alone is not a data migration: it creates neither the subvolume nor snapshot destination and does not transfer snapshot history.

Treat historical snapshots as a separate migration requirement. Ordinary rsync copies do not preserve their Btrfs identity. A planned Btrfs send/receive transfer uses read-only source subvolumes to transfer filesystem structure, but UniFi registration, paths, schedules, and historical snapshot mapping still need separate handling. This was not tested in the pilot; use an explicitly reviewed/vendor-supported procedure if history must be retained. Btrfs send documentation.

Acceptance checklist before retiring the source#

• Destination share root confirmed as a Btrfs subvolume.
• Separate .snapshot/<share> container exists with correct ownership/mode.
• File contents and required metadata verified after writers were paused.
• User access, quota limits, and SMB/NFS/rsync exports verified.
• Manual snapshot succeeds; its contents and read-only status verified.
• Next scheduled snapshot and relevant backup jobs succeed.
• Historical snapshot retention or loss explicitly accounted for.
• Rollback/source data retained until acceptance; cleanup separately approved.

10. Related records#

• Unifi UNAS-Pro Pool Migration Strategy — historical August 2 emergency migration.
• Unifi UNAS-Pro Backup Strategy — rsync pull-backup architecture and fleet configuration.