Troubleshooting UNAS Backup Issues

• Possible Cause: Files are being modified while the backup is running (e.g., Time Machine is active).
• Solution:
  • Avoid modifying files during backup.
  • Pause Time Machine or similar services before starting the backup.

• Possible Cause: Some systems reject files with special characters (e.g., @eadir for Synology and .@__thumb for QNAP).
• Solution: Use the All Files view to locate and rename problematic files. Refer to the file naming guidelines for:
  • Synology
  • Dropbox
  • OneDrive

• Possible Cause: Backups pause when the console name changes to prevent duplicate entries.
• Solution: A prompt appears to guide you to rename the backup folder.
  1. Go to your backup destination and find the folder name "UniFi Drive_[Old Console Name]":
     • UNAS or SMB/CIFS server: Your destination folder > UniFi Drive_[Old Console Name]
     • Google Drive: My Drive > UniFi Drive_[Old Console Name]
     • OneDrive: My Files > UniFi Drive_[Old Console Name]
     • Dropbox: All Files > Apps > UniFi Drive Backup > UniFi Drive_[Old Console Name]
  2. Rename the folder to "UniFi Drive_[New Console Name]/[New Console Name]_[Task Name]".
     • If the destination folder already exists with that name, change the task name in UNAS to avoid conflicts.
  3. Return to the backup task on UNAS, click Dismiss and Resume Backup.

• Possible Cause: Backups to another UNAS or CIFS/SMB server may fail if source folders contain files that differ only by letter case (e.g., test.txt vs. Test.txt). Only one of these will be backed up.
• Solution:
  • Rename files to eliminate case-only differences before starting the backup.
  • If a partial success message appears, locate and rename the conflicting files, and retry the backup.

• Possible Cause: When performing an off-site backup between two UNAS devices, backups to encrypted drives fail if file paths exceed 143 characters, due to encryption-related path length limits.
• Solution:
  • Shorten source folder or file names to ensure total path length stays under 143 characters.
  • Use a non-encrypted drive as the backup destination to avoid this limitation.

• Description: A "Server Connection Failed" error appears when attempting a remote backup between two UNAS devices. This means the local system couldn't connect to the remote server.
• Possible Cause:
  • Network Unreachable: The remote UNAS is offline or unreachable.
  • VPN Not Connected: VPN or Site Magic is not active or misconfigured.
  • IP Conflict: Both local and remote UNAS devices use the same LAN subnet (e.g., 192.168.1.x), preventing VPN routing.
  • SMB Disabled: SMB service is disabled or access permissions are incorrect on the remote UNAS.
• Solution:
  • Check Network & VPN
    1. Ensure both UNAS devices are online and reachable.
    2. Ping the remote UNAS from the local network.
       1. Enable SSH and remember the SSH password in Site Manager > UniFi Console > Settings > Control Plane > Console > Advanced > SSH.
       2. Run the following commands on a computer connected to the UniFi Console network.
          • Replace UNIFI_GATEWAY_LAN_IP with your console's LAN IP.

          • Replace UNAS_IP with the actual IP of the device experiencing the issue.

            ssh root@UNIFI_GATEWAY_LAN_IP
            ping UNAS_IP

    3. Confirm Site Magic or VPN status shows Connected.
  • Check IP Configuration: Use different subnets for the local and remote UNAS (e.g., 192.168.1.x for local UNAS and 192.168.11.x for remote UNAS) to avoid conflicts.
  • Verify SMB Service & Permissions
    1. On the remote UNAS, ensure SMB is enabled.
    2. Confirm that remote access permissions are correctly set.

• Description: If you rename your console, the folder or object names used in Amazon S3, Backblaze B2, or Wasabi backup tasks will remain unchanged.
• Cause: These cloud storage providers do not support renaming folders or objects after creation. As a result, the backup destination retains the original console name used at the time the task was created.
• Result: Backup tasks will continue to run normally. This does not affect backup functionality or data integrity.

See this article for best practices on backing up UNAS data to Amazon S3, Backblaze B2, and Wasabi.

• Description: The error "Backblaze B2 transaction cap exceeded. Please update your cap settings or try again tomorrow." occurred when setting up or running a backup task to Backblaze B2.
• Cause: This error occurs when the total number of API transactions exceeds the 24-hour quota for your Backblaze B2 account. Backblaze enforces transaction caps to manage costs and API usage. Transactions include actions such as:
  • Connecting with your Application Key.
  • Creating or listing buckets.
  • Uploading individual files (b2_upload_file).
  • Listing files or retrieving metadata.
• Common triggers include:
  • Frequent retries due to misconfigured permissions or incorrect bucket names.
  • Uploading a large number of small files in one backup task.
  • Multiple tasks using different Application Keys under the same account. All Application Keys share the same transaction quota across the account.
  • Running frequent automated backup tasks (e.g., hourly incremental backups).
• Solution:
  • Wait for the daily reset: The cap resets every 24 hours (UTC). The task will automatically retry after reset.
  • Increase the transaction cap: If you're using a paid B2 plan, go to Caps & Alerts in your Backblaze Console and adjust your Daily Transaction Cap to a higher value.

• Description: When performing a local backup to a USB drive formatted as exFAT or FAT32, the task may complete with a "Partially Successful" status and display the error code "E_FAILED." This usually occurs when files in the source folder differ only by letter casing (for example, Photo.jpg and photo.jpg).
• Cause: exFAT and FAT32 are case-insensitive file systems, meaning they treat filenames with different capitalization as identical.
• Solution:
  • Rename the conflicting files in the Shared Drive of your UNAS so each filename is unique, regardless of capitalization.
  • If possible, reformat the USB drive to ext4, which supports case-sensitive file naming and is fully compatible with the UNAS file system.

• Description: When backing up data to an external USB drive, Extended Attributes (xattr), such as file tags or application metadata, are not preserved. The backup task will still complete with a "Succeeded" status.
• Cause: 
  • Compatibility considerations: USB drives are commonly used across different operating systems (Windows, macOS, Linux), which handle xattr differently. To ensure files remain accessible across platforms, UniFi Drive prioritizes core file data.
  • System-specific metadata: Extended Attributes are primarily used by the UNAS system for internal functions (such as indexing) and are not required for typical file access.
• Result: Your files remain intact and fully usable, but certain metadata (such as tags or indexing information) will not be retained after the backup.

• Description: When backing up data to an encrypted shared folder or encrypted destination, the task may fail if the filename (including its extension) exceeds the allowed character limit.
• Cause: Encrypted file systems require additional space to store encryption metadata. While standard Linux file systems (Btrfs/ext4) support up to 255 characters, the encryption layer typically reduces the maximum filename length to approximately 140–143 characters.
• Solution:
  • Rename the source files to ensure each filename (including its extension) is well below 140 characters to account for encryption overhead and temporary backup suffixes.
  • If long filenames are required, consider using a non-encrypted destination that supports the full 255-character limit.

• Description: During a local backup task, the progress bar may reach 100% but remain there for an extended period without completing. This is often accompanied by high system activity but no visible progress in the user interface.
• Cause: If the system encounters errors while backing up specific files (for example, file name too long due to destination encryption or temporary network issues), it will automatically trigger retries. Each retry involves re-scanning and comparing the entire file list between the source and destination to ensure data integrity. For backups with a large number of files (such as tens of thousands of small files), this process can take a significant amount of time.
• Solution:
  • Wait for completion: No manual intervention is required. Stopping the task during retries may result in an incomplete backup.
  • Check filenames and logs: Review logs for errors such as file name too long or case conflicts. Shortening filenames or resolving naming conflicts can prevent repeated retries and speed up completion.

• Description: When attempting to push backups from another NAS or server to UniFi Drive using rsync, you may encounter:
  • Connection failed errors.
  • Tasks that hang or time out, even if the file list is visible.
• Cause: Some source devices only support rsync over SSH, which is not compatible with UniFi Drive's implementation. UniFi Drive requires rsync daemon mode with enforced security policies, including:
  • Path isolation: The backup user can only access the designated backup folder.
  • No shell access: Prevents executing commands on the NAS through the backup connection.
• Result: The connection may partially work (such as listing files) but fail or time out when attempting to transfer data.
• Solution:
  • On the source device: Ensure the rsync daemon service is enabled (typically using port 873).
  • On UniFi Drive: 
    1. Navigate to Backup Tasks > Create Backup Task > Local Backup > rsync.
    2. Enter the source device details.
    3. Choose Daemon Mode for Transfer Encryption. 
    4. Connect and select the folders to back up.
    5. Create the task. 

• Description: When migrating large datasets or system backups that use hard links (multiple filenames pointing to the same data) or sparse files, you may want to preserve the original storage structure to avoid unnecessary disk usage.
• Recommendation: To maintain data integrity and storage efficiency, use the rsync engine in UniFi Drive, which supports preserving hard links and sparse files. Depending on your workflow, you can configure it in one of the following ways:
  • Pull data to UniFi Drive: Navigate to Backup Tasks > Create Backup Task > rsync, then configure the task to retrieve data from your source rsync server.
  • Allow a remote server to pull data from UniFi Drive: Enable the rsync service in Settings > Services, then initiate the backup from your remote server using UniFi Drive as the source.

• Description: The tenant setup fails during the initial connection or authorization stage in UniFi Drive.
• Possible Causes: 
  • Microsoft Entra ID security policy: The setting Block new password credentials in apps is enabled, preventing authentication.
  • Gateway restrictions: Geo-blocking or ad-blocking on your UniFi Gateway may block access to Microsoft authentication endpoints. 
• Solutions: 
  1. Sign in to the Microsoft Entra admin center as a Global Administrator and temporarily disable Block new password credentials in apps.
  2. Ensure your UniFi Gateway is not blocking regions or endpoints used by Microsoft services.
  3. Return to UniFi Drive and complete the setup.

• Possible Causes: Microsoft 365 Security Groups are designed for access control (e.g., SharePoint, OneDrive, Teams, and admin roles) and typically do not have associated email addresses. As a result, sharing permissions that rely on email-based identification cannot be restored.
• Solutions: Manually reassign permissions after restoring data. For future use, consider using Microsoft 365 Groups, which include mailboxes and support permission restoration. 

• Possible Causes: 
  • Unlicensed users: Accounts without a valid Microsoft 365 license are not backed up.
  • Guest users: External guest accounts are not included in backups.
  • OneDrive not initialized: If a user has never signed in to the OneDrive web portal, their personal storage (Personal Site) may not exist.
• Solutions:
  1. Verify license and account type.
     1. Confirm the user has an active Microsoft 365 Business or Enterprise license. 
     2. Ensure the account is an internal user (not a Guest).
  2. Initialize OneDrive.
     1. Have the user sign in to the OneDrive web portal at least once. 
     2. Confirm their files and folders are visible. 
  3. Retry backup.
     1. Wait 5–10 minutes for Microsoft services to sync.
     2. Refresh the user list or rerun the backup task in UniFi Drive.