• View
• Edit
• History
• Print

Unison FAQ: Troubleshooting

Are there any general troubleshooting strategies?

A general recommendation is that, if you've gotten into a state you don't understand, deleting the archive files on both replicas (files with names like arNNNNNNNNN in the .unison directory) will return you to a blank slate. If the replicas are identical, then deleting the archives is always safe. If they are not identical, then deleting the archives will cause all files that exist on one side but not the other to be copied, and will report conflicts for all non-identical files that do exist on both sides.

(If you think the behavior you're observing is an actual bug, then you might consider moving the archives to somewhere else instead of deleting them, so that you can try to replicate the bad behavior and report more clearly what happened.)

If unison fails on some unspecified file, try running with the -debug all flag to help determine if some particular file is causing the failure. If you are not a developer, be prepared for lots of messages not designed for end-users -- however, the output may still help you narrow down the problem and file a bug report, if appropriate.

Why do I keep getting "Warning: No archive files were found for these roots"?

This can happen if your hostname changes (for example, one of the hosts might be a laptop that changes hostname when changing the network it's on). In this case, unison will believe a new archive is needed (as it's a new machine), and do an initial synchronization. For this synchronization, as no previous state exists, and unison does not know what to do when the files differ.

There are a couple of ways to address this problem. The simplest and safest is using the UNISONLOCALHOSTNAME variable. Otherwise you can look into the "rootalias" profile setting, but it's more dangerous to use.

The text mode user interface fails with "Uncaught exception Sys_blocked_io" when running over ssh2.

The problem here is that ssh2 puts its standard file descriptors into non-blocking mode. But unison and ssh share the same stderr (so that error messages from the server are displayed), and the nonblocking setting interferes with Unison's interaction with the user. This can be corrected by redirecting the stderr when invoking Unison:

     unison -ui text <other args> 2>/dev/tty

(The redirection syntax is a bit shell-specific. On some shells, e.g., csh and tcsh, you may need to write

     unison -ui text <other args>  > & /dev/tty

instead.)

What does "DANGER.README: permission denied" mean?

If you see something like

it means that unison is having trouble creating the temporary file DANGER.README, which it uses as a "commit log" for operations (such as renaming its temporary file accounting/fedscwh3qt2000.wb3.unison.tmp to the real location accounting/fedscwh3qt2000.wb3) that may leave the filesystem in a bad state if they are interrupted in the middle. This is pretty unlikely, since the rename operation happens fast, but it is possible; if it happens, the commit log will be left around and Unison will notice (and tell you) the next time it runs that the consistency of that file needs to be checked.

The specific problem here is that Unison is trying to create DANGER.README in the directory specified by your HOME environment variable, which seems to be set to /, where you do not have write permission.

The command line "unison work ssh://remote.dcs.ed.ac.uk/work" fails, with "fatal error: could not connect to server." But when I connect directly with ssh remote.dcs.ed.ac.uk/work, I see that my PATH variable is correctly set, and the unison executable is found.

In the first case, Unison is using ssh to execute a command, and in the second, it is giving you an interactive remote shell. Under some ssh configurations, these two use different startup sequences. You can test whether this is the problem here by trying, e.g.,

and seeing whether your PATH is the same as when you do

One method that should always work is this [thanks to Richard Atterer for this]: log into the machine, set up PATH so the program is found execute

All this seems to be controlled by the configuration of ssh, but we have not understood the details---if someone does, please let us know.

NB- this is usually because the option PermitUserEnvironment in /etc/sshd_config is set to 'no' (for example, MacOSX ships with this set to NO). You should be able to set it to 'yes' and things will be golden.

When I use ssh to log into the server, everything looks fine (and I can see the Unison binary in my path). But when I do 'ssh <server> unison' it fails. Why?

[Thanks to Nick Phillips for the following explanation.]

It's simple. If you start ssh, enter your password etc. and then end up in a shell, you have a login shell.

If you do "ssh myhost.com unison" then unison is not run in a login shell.

This means that different shell init scripts are used, and most people seem to have their shell init scripts set up all wrong.

With bash, for example, your .bash_profile only gets used if you start a login shell. This usually means that you've logged in on the system console, on a terminal, or remotely. If you start an xterm from the command line you won't get a login shell in it. If you start a command remotely from the ssh or rsh command line you also won't get a login shell to run it in (this is of course a Good Thing -- you may want to run interactive commands from it, for example to ask what type of terminal they're using today).

If people insist on setting their PATH in their .bash_profile, then they should probably do at least one of the following:

• stop it;
• read the bash manual, section "INVOCATION";
• set their path in their .bashrc;
• get their sysadmin to set a sensible system-wide default path;
• source their .bash_profile from their .bashrc ...

It's pretty similar for most shells.

Unison crashes with an "out of memory" error when used to synchronize really huge directories (e.g., with hundreds of thousands of files).

You may need to increase your maximum stack size. On Linux and Solaris systems, for example, you can do this using the ulimit command (see the bash documentation for details).

Why does unison run so slowly the first time I start it?

On the first synchronization, unison doesn't have any "memory" of what your replicas used to look like, so it has to go through, fingerprint every file, transfer the fingerprints across the network, and compare them to what's on the other side. Having done this once, it stashes away the information so that in future runs almost all of the work can be done locally on each side.

I can't seem to override the paths selected in the profile by using a -path argument on the command line.

Right: the path preference is additive (each use adds an entry to the list of paths within the replicas that Unison will try to synchronize), and there is no way to remove entries once they have gotten into this list. The solution is to split your preference file into different "top-level" files containing different sets of path preferences and make them all include a common preference file to avoid repeating the non-path preferences. See the section "Profile Examples" of the user manual for a complete example.

I can't seem to override the roots selected in the profile by listing the roots on the command line. I get "Fatal error: Wrong number of roots (2 expected; 4 provided)."

Roots should be provided either in the preference file or on the command line, not both. See the section "Profile Examples" of the user manual for further advice.

Another cause for this error can be the path to unison executable not quoted properly for 2.40.61 if you're running from a batch script, example:

C:\"Program files"\"Unison-2.40.61 Gtk+.exe" MYPROFILE -fastcheck true -batch

worked with Unison 2.32.52 but gives this error with 2.40.61. Changing the line to:

"C:\Program files\Unison-2.40.61 Gtk+.exe" MYPROFILE -fastcheck true -batch

solves this.

I get a persistent 'rsync failure' error when transferring a particular file. What can I do?

We're not sure what causes this failure, but a workaround is to set the rsync flag to false.

I find that I get time-out problems when shifting large amounts of data with Unison

This is probably not a Unison problem as such. The usual reason for timeout problems is that Unison is taking a long time to compute fingerprints for a large amount of data that it has never seen before (e.g., because this is the very first sync) and so the lower-level program that is maintaining the connection (typically ssh) times out and disconnects. A rule of thumb is that if your Unison is taking an hour or more to do what you expect then you may need to re-think your strategy to avoid problems with timeouts.

(For ssh, I eliminated the repeated timeouts I was experiencing during the long, one-hour-plus sync of a linux client with a new linux host [both on the same LAN] by increasing the ServerAliveInterval value [from 60s to 600s] in my client's $HOME/.ssh/config file. On my client host, whence I was invoking unison at the command line, I set my server's stanza like so:

     Host mybrandnewserver
          Hostname            mybrandnewserver
          ForwardX11          yes
          ForwardX11Trusted   yes
          ServerAliveInterval 600s

--ead[dash]unison[at]ixian[dot]com, "unison version 2.51.2 (ocaml 4.02.3)" [both client and server], "This Unison binary only provides the text GUI..." [both client and server], under Devuan 2.0.0 [both client and server], 2019-04-22)

The best way to deal with this is to run Unison on smaller chunks of data, the first time. (Later, when its archive is built and it just needs to check file modification times, scanning for updates is much faster and you can do everything all together.) See the documentation of the "-path" preference for instructions on how to do this.

Sometimes network problems interrupt Unison's operation during large transfers of data from one computer to another. When this happens, Unison will (conservatively) delete all the data that has already been transferred. To prevent this, it often helps to create an empty folder structure on the target before starting transferring the data -- that way, the transfer will be broken up into small chunks and an interruption of network service will cause only one of them to fail and be deleted when Unison is re-run.

I get `Uncaught exception Invalid_argument("String.sub")' when using unison to copy a directory.

Unison 2.17.1 may crash after attempting to syncronize an existing directory with a non-existing directory. Create an empty directory in place of the non-existing directory to work around this problem.

A blank character at the end of the directory name can cause this error, e.g. "Directory ". In most cases, this is not desired. To solve it, you just need to rename the directory, remove the blank and rescan.

I get 'bash: unison: command not found' after entering the SSH password.

Make sure Unison is installed on the host you are trying to connect to.

I get something like 'Fatal error: Received unexpected header from the server: expected "Unison 2.13\n" but received "Unison 2.17\n\000\000\000\000", which differs at "Unison 2.17".'

The versions of unison running on the server and the client must match. (Specifically, the first two components of the version number must match exactly: versions 2.24.6 and 2.24.10 will happily talk to each other, but 2.17.3 and 2.24.10 will not). If all you need is the textual user interface, compiling binaries for most distributions is straighforward.

Since also the ocaml versions must match, it can be easier to run a docker-container on the server side: https://github.com/AlterDepp/unison-docker.

I get something like "Fatal error: Error in creating directory: No such file or directory [mkdir(C:/Documents and Settings/my_user_name/.unison/backup/My Documents/caryd/2005_taxes)]"

We're not sure why this happens. It seems to be related to using the "backup" preference (rather than the "backups"-with-an-s preference). Work-around: manually create the directory it wants, then run Unison again.

When I try to synchronize to a remote host via SSH, Unison gives the error, "Fatal error: Warning: the archives are locked". The message gives the name of a lock file to delete, but the lock file does not exist.

This problem occurs when you try to synchronize via SSH to your own local host. You can use Unison to synchronize files that are on the same host computer, but not using SSH.

To diagnose this situation, try the following on your local host. For example, suppose that the local and remote hosts are:

    local.upenn.edu, IP address 192.168.1.200
    remote.upenn.edu, IP address 192.168.1.201

1. Use the ifconfig command to find out your local host IP address. On Windows, use ipconfig. In this example, the local host IP address should be 192.168.1.200.
2. Use the ssh remote.upenn.edu command to log in to the remote host
3. Use the hostname command to find out the remote host name. In this example, it should be remote.upenn.edu.
4. Use the ifconfig command to find out the remote host IP address. In this example, it should be 192.168.1.201.
5. Use the exit command to return to your local host

If you are getting the Unison "archives are locked" error, you will probably find that the remote IP address found in step 4 is the same as the IP address of your local host, not the IP address of the remote host.

This can happen due to a variety of network configuration problems:

• You really do intend to synchronize files on the local host, but you specified SSH. Use Local instead.
• Earlier you specified a numeric IP address for the remote machine. But now, DHCP has by chance assigned this IP address to your local machine. Thus your local host and remote host are the same.
• Your /etc/hosts file incorrectly specifies the IP address of your local machine for the remote host name

When I try to run unison on my unix/linux machine, I get a message saying it can't find the files included by my sync profile - and the message is spelled wrong, too! ("not foundr: ...")

Did you copy your profile files from a Windows machine? The problem most likely is that there are Windows-style end of line characters in the profile definition files, line feed characters to be more specific. You should use a utility like dos2unix to remove them, then unison should run fine.

I am over a VPN. When unison is copying large files, it often leads to "lost connection to the server".

This is actually not a unison problem, the same problem randomly arises when copying large files using scp (over the same VPN connection). Yet, this prevents from using unison successfully.

Cause: the MTU of my VPN connection is smaller than the MTU of my remote ethernet connection. To see this, just type ifconfig on both machines and look at the MTUs of the network interfaces that are used by unison. As a result of this mismatch, some parts of messages are randomly lost (search "MTU mismatch" on the internet).

Solution: adjust both MTU to similar values. For instance: ifconfig eth0 mtu 1400 (on the remote server) ifconfig tun0 mtu 1400 (on my local machine)

I often get random "Error in renaming U:/Path/.unison.FILENAME.f588d1.unison.tmp to U:/Path/FILENAME:"

Permission denied [rename(U:/Path/.unison.FILENAME.f588d1.unison.tmp)] on random directories creation

On some directories the anti-virus software is still scanning them, holding them open when Unison tries to rename the tmp directory to its final name. Hence the rename fails.

Maybe your particular antivirus can allow patterns like .unison.*.unison.tmp to be excluded from scanning.

But if your antivirus allows it and you only sync with safe sources, you can exclude unison process (in fact the files opened by it) from real-time scan.

For Avira:

• go to configuration, check 'Expert mode'
• unfold and select Guard => Search => Exceptions
• In the processes section: click Add
• Type the name of the executable file (on my box: Unison-2.40.61 Gtk+.exe)
• Apply changes to AV and retest Unison sync

As an added bonus the synchronisation is about 2x faster now.