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.
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.
[Sadly not true!]
The above explanation is sadly not true, because in case you run "ssh <server> unison" actually none of .bash_profile or .bashrc gets executed (ssh executes "unison" instead of a shell).
As mentioned in it's manpage, the $PATH ssh uses to locate "unison" is specified at compile time.
As explained one question above, the $PATH can be modified using ~/.ssh/environment, but only if allowed by the remote sshd (by setting the "PermitUserEnvironment" to "yes" in it's sshd_config).
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.
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.
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.
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.
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 always complains that there is a lock-file on the local host preventing the sync. But if I check after exiting unison, there is no lockfile.
This might happen if you accidentally synchronize to your own host address. For me, this happened in a DHCP-controlled network where the client machine suddenly got the IP address I saved for the server in the Unison profile.