Troubleshooting and limits
Start at the share: Servers & clients → File shares, choose the share. A failed test, the Overview and the sheet of a failed run name the cause with the first step to take, and a run lists the files with a warning. The causes are the codes below (share. and a name). For problems with the mounter itself, look at its log on the Docker host, in the installation directory:
docker compose logs mounterCauses
Section titled “Causes”Connecting
Section titled “Connecting”| Cause | What it means and what to do |
|---|---|
share.auth_failed (“The file server refused the account”) |
The password is wrong or was changed, the account is locked, it has expired, or it has no access to this share. Nothing was read. Enter the new password under Settings of the share (the share does not have to be added again) and check that the account is not locked. The share shows “The password was refused” until a test or a run succeeds. |
share.unreachable (“The file server did not answer”) |
The Docker host gets no answer: check the address, the firewall (445 for SMB, 2049 for NFS), the VPN for a remote site, and the routing from the host, not from your PC. |
share.not_found (“The share, export or folder does not exist”) |
The share name, the NFS export or the subfolder is wrong or was removed. On NFS, showmount -e <server> lists what the server exports. |
share.version_mismatch (“The server does not speak the selected protocol version”) |
Choose another version under Settings (for SMB, 3.0 is the most compatible) or switch Encrypt the connection off. For NFS try another version. |
share.permission_denied (“The account may not read this folder”) |
The share mounted, but the account may not list the folder. Give it read rights, ideally through Backup Operators. |
share.client_missing (“The Docker host has no SMB or NFS client”) |
Load the kernel client on the Docker host: modprobe cifs (on Ubuntu cloud kernels install linux-modules-extra-$(uname -r) first), or install nfs-common or nfs-utils. See Overview and requirements. |
share.mount_failed (“The share could not be mounted”) |
Mounting failed for a reason Restow does not recognise. The technical details show what the system reported (the password is removed from it). |
share.address_blocked (“The server’s address is not allowed”) |
A private, loopback or reserved address that no provider administrator approved for this share, or an address outside the approved range. Approve the share, or switch on Tenants may add file shares in private networks, see Budgets, networks and runners. |
share.wrong_filesystem (“The share was not mounted as expected”) |
The runner did not find the share mounted where it expected it, and read nothing. This should not happen: open a support case. |
Backing up
Section titled “Backing up”| Cause | What it means and what to do |
|---|---|
share.empty_source (“The share is empty”) |
The share, or the folders of the job, are empty although the last restore point had files. Nothing was backed up and nothing is removed. Check the share, and choose Back up the empty share once if it is meant to be empty, see An empty share. |
share.include_missing (“An included folder no longer exists”) |
A folder of the job is gone. Correct the folders of the job. |
share.quota_exceeded (“The storage budget for file share backups is used up”) |
Raise the budget or tighten the retention, see Budgets. |
share.out_of_memory (“The runner ran out of memory”) |
Raise Memory per runner under File share runners, see Runner settings. |
share.timeout (“The run took too long”) |
The run did not finish within Longest run (hours) and was stopped. Raise it under File share runners, or back the share up in smaller parts. |
Warnings
Section titled “Warnings”A run that ends With warnings made a restore point of what it could read. The files are listed in the run.
| Cause | What it means and what to do |
|---|---|
share.locked_files (“Some files were open on the server”) |
The files were open with a lock and could not be read. The rest is complete. Back up at night. There is no VSS over SMB. |
share.read_errors (“Some files could not be read”) |
Other per-file read errors. The rest is complete. |
share.files_dropped (“Far fewer files than last time”) |
The share holds fewer than half the files of the previous restore point. It was backed up as found. Check that the files were deleted on purpose, before retention removes the older restore points. |
share.acl_partial (“Permissions were not saved or restored for every file”) |
The account lacks the right to read or write the permissions of some files. Use Backup Operators, and SeSecurityPrivilege for auditing entries. |
share.offline_skipped (“Offline files were skipped”) |
Files that exist only as placeholders (tiered to the cloud or an archive) were skipped, as the job says. Switch on Recall offline files to back them up. |
Acknowledge a warning on the Warnings page when it is expected. A failure afterwards supersedes the acknowledgement.
Restoring and copying
Section titled “Restoring and copying”| Cause | What it means and what to do |
|---|---|
share.restore_not_allowed (“The target share does not allow restores”) |
Switch on Allow restore to this share in the target’s settings, or choose another target. |
share.restore_partial (“Some files could not be written”) |
A name the target cannot hold, missing rights, or no space. The run ends With warnings and lists the files. |
share.copy_no_verified_point (“No checked restore point to copy yet”) |
Wait for the restore check of the source’s newest restore point, or start it on the source share. |
share.copy_unsafe_target (“The copy target is not safe”) |
The target breaks a safety rule: the same place, the root of a share for a mirror, a folder of another copy job, or a non-empty folder nobody confirmed. Check the copy job. |
share.copy_empty_source (“Mirror copy refused: the source looks emptied”) |
The restore point is empty or has fewer than half the files of the last copy. Check the source. Copy anyway copies the smaller state once; an empty restore point is never mirrored. |
See Copy jobs.
Mounter and runner
Section titled “Mounter and runner”| Cause | What it means and what to do |
|---|---|
share.mounter_unavailable (“The mounter is not running”) |
The mounter is off, restarting, or cannot start runners right now (network, image or limit). Scheduled runs wait. Installation → Default repository & network shares shows why, and docker compose logs mounter the details. |
share.runner_failed (“The runner ended without a result”) |
The runner stopped before it reported how the run ended (with its exit code). Look at the log of the run and the mounter. |
share.runner_lost (“The runner disappeared”) |
The mounter no longer knows the runner of this run, for example because the mounter was stopped or restarted while the run was going. |
share.runner_stalled (“The runner stopped reporting”) |
The runner sent no progress for a long time (30 minutes) and was stopped. |
When the mounter runs but File share runs cannot start, the page names the blocker. runner_network_missing means the docker-compose.yml is older than 0.4.0 and has no runners network: run the install.sh of 0.4.0 or newer again, see Running it again. runner_image_unknown means the mounter found no api container of the Compose project to take the runner image from. Runners always use the image of the running api, so that they speak the same version.
The repository
Section titled “The repository”| Cause | What it means and what to do |
|---|---|
share.repository_locked (“The restic repository of the share stayed locked”) |
Another run or the server’s maintenance held the repository locked. Restow tries again. Locks of finished runs are cleared by retention and the weekly check. A repository that stays locked for more than twelve hours raises Backup data of a file share stays locked. |
share.repository_damaged (“The restic repository of the share reported damage”) |
restic reports the repository as damaged or cannot open it. The share is rated Not restorable. Open the repository with its password (Show password) and run restic check by hand, and ask for help with the output. |
SELinux
Section titled “SELinux”On a host with SELinux enforcing, a container cannot read a cifs or nfs mount without a context= option. The sign is a test that mounts but then reads “Permission denied”. Set RESTOW_MOUNTER_SELINUX_CONTEXT=true in the environment of the mounter service and recreate it, see the Docker host. The release notes list SELinux enforcing as untested.
Known limits
Section titled “Known limits”These are the limits of file share backup in 0.4.7.
- No VSS over SMB. Restow reads the files one after another while people work. A file that is open with an exclusive lock is skipped (Locked by another program), and there is no consistent state across files. Back up at night. For databases and mail files (PST, for example) use the endpoint agent with VSS on the server.
- No alternate data streams. The Linux SMB client does not show them (the
Zone.Identifiermark, Office metadata, the resource forks of macOS). They are not backed up and not restored. - No DFS namespaces, no Kerberos, no SMB 1. DFS referrals are switched off, so that the kernel never connects to a server Restow did not judge: add the target shares of a namespace directly. Sign-in is NTLMv2, and NFS authenticates by host.
- Permissions. Access times are not kept. The owner and mode that the Linux SMB client shows are synthetic and not restored; the NTFS permissions come from the saved permissions. The permissions of a single file are restored only together with the file.
- Repositories live on the primary repository only. Restow does not mirror them to a copy repository, as for the restic repositories of machines and Proxmox VE containers. Back the primary repository up, see Backing up Restow itself. Since 0.4.2 a storage move copies them to the new primary, checked by size and SHA-256 (before 0.4.2 it did not), and Keep existing backups where they are is refused while file shares have repositories, see Replacing the primary repository.
- A missing repository is not healed yet. If the repository of a file share is missing from the primary after a storage change, the backups of the share can fail, typically with restic’s message that the repository does not exist: Restow does not begin a new backup chain for it the way it does for a container (New backup chain). This is a known issue in 0.4.2, and healing it is planned. To avoid it, change the primary repository with a storage move, which takes the repository along, and not with “keep”, which is refused while file shares have repositories.
- One mounter per installation, runners on the Docker host only. There is no runner near the file server: a file server reachable over a slow link is backed up over that link.
- A copy job keeps no versions. See Copy jobs.
- Tenant users have no self-service restore of shares. Only administrators restore, see Restore and restore checks.
- Scheduled reports have no block of their own for file shares. The figures a report quotes (backup success rate, share proven restorable) include them.
- Immutable backups. A file share whose repository is still locked cannot be purged before the lock has run out, see Immutable backups.
- Storage figures. Since 0.4.1 Stored (Repositories → Usage, the dashboard tile, the statistics and
physicalBytesof the API) includes the restic repositories of file shares. A repository’s size has no history, so the growth and the deduplication saving remain figures of the chunk store, and Protected data does not count the logical size of restic backups. - arm64 hosts are supported as far as the image is. The kernel needs the
cifsmodule.
What was tested
Section titled “What was tested”The known issues of 0.4.0 state it, and they still apply in 0.4.7. Since 0.4.2 the known issues also say that the new parts were tested against a simulated S3 store only, never against a real S3 provider, and that a file share’s missing repository is not healed yet (see above):
- File shares were tested against Samba in the release smoke run (back up, browse, search, ZIP download, restore with permissions and a copy job), and in the test suites against simulated services. They were not tested against Windows Server (NTFS permissions, Backup Operators, a file kept open in Excel), a Synology or TrueNAS share, real NFS exports (NFS is not part of the smoke run) or a host with SELinux enforcing.
- Enable network shares and the move of the database were not tested through a real updater and its Docker helper container.
- The new pages were covered by component tests, not tried by hand in a browser before the tag.
Start with a test share, restore from it, and keep your existing backup of the file server until you have restored from Restow yourself.