Collisions in nix-env
Symptom: when installing or upgrading, you get an error message such as
$ nix-env -i docbook-xml
...
adding /nix/store/s5hyxgm62gk2...-docbook-xml-4.2
collision between `/nix/store/s5hyxgm62gk2...-docbook-xml-4.2/xml/dtd/docbook/calstblx.dtd'
  and `/nix/store/06h377hr4b33...-docbook-xml-4.3/xml/dtd/docbook/calstblx.dtd'
  at /nix/store/...-builder.pl line 62.
The cause is that two installed packages in the user environment
have overlapping filenames (e.g.,
xml/dtd/docbook/calstblx.dtd.  This usually
happens when you accidentally try to install two versions of the same
package.  For instance, in the example above, the Nix Packages
collection contains two versions of docbook-xml, so
nix-env -i will try to install both.  The default
user environment builder has no way to way to resolve such conflicts,
so it just gives up.
Solution: remove one of the offending packages from the user
environment (if already installed) using nix-env
-e, or specify exactly which version should be installed
(e.g., nix-env -i docbook-xml-4.2).
Alternatively, you can modify the user environment builder
script (in
prefix/share/nix/corepkgs/buildenv/builder.pl)
to implement some conflict resolution policy.  E.g., the script could
be modified to rename conflicting file names, or to pick one over the
other.