1 files changed, 92 insertions, 0 deletions
diff --git a/doc/manual/troubleshooting.xml b/doc/manual/troubleshooting.xml
new file mode 100644
index 000000000000..ec8c4c924fc7
--- /dev/null
+++ b/doc/manual/troubleshooting.xml
@@ -0,0 +1,92 @@
+<appendix xmlns="http://docbook.org/ns/docbook"
+          xmlns:xlink="http://www.w3.org/1999/xlink">
+
+<title>Troubleshooting</title>
+
+
+<para>This section provides solutions for some common problems.  See
+the <link xlink:href="http://bugs.strategoxt.org/browse/NIX">Nix
+bug tracker</link> for a list of currently known issues.</para>
+
+
+<section><title>Collisions in <command>nix-env</command></title>
+
+<para>Symptom: when installing or upgrading, you get an error message such as
+
+<screen>
+$ 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.</screen>
+
+</para>
+
+<para>The cause is that two installed packages in the user environment
+have overlapping filenames (e.g.,
+<filename>xml/dtd/docbook/calstblx.dtd</filename>.  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 <literal>docbook-xml</literal>, so
+<command>nix-env -i</command> will try to install both.  The default
+user environment builder has no way to way to resolve such conflicts,
+so it just gives up.</para>
+
+<para>Solution: remove one of the offending packages from the user
+environment (if already installed) using <command>nix-env
+-e</command>, or specify exactly which version should be installed
+(e.g., <literal>nix-env -i docbook-xml-4.2</literal>).</para>
+
+<para>Alternatively, you can modify the user environment builder
+script (in
+<filename><replaceable>prefix</replaceable>/share/nix/corepkgs/buildenv/builder.pl</filename>)
+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.</para>
+
+</section>
+
+
+<section><title><quote>Too many links</quote> error in the Nix
+store</title>
+
+
+<para>Symptom: when building something, you get an error message such as
+
+<screen>
+...
+<literal>mkdir: cannot create directory `/nix/store/<replaceable>name</replaceable>': Too many links</literal></screen>
+
+</para>
+
+<para>This is usually because you have more than 32,000 subdirectories
+in <filename>/nix/store</filename>, as can be seen using <command>ls
+-l</command>:
+
+<screen>
+$ ls -l /nix/store
+drwxrwxrwt 32000 nix nix 4620288 Sep 8 15:08 store</screen>
+
+The <literal>ext2</literal> file system is limited to an inode link
+count of 32,000 (each subdirectory increasing the count by one).
+Furthermore, the <literal>st_nlink</literal> field of the
+<function>stat</function> system call is a 16-bit value.</para>
+
+<para>This only happens on very large Nix installations (such as build
+machines).</para>
+
+<para>Quick solution: run the garbage collector.  You may want to use
+the <option>--max-links</option> option.</para>
+
+<para>Real solution: put the Nix store on a file system that supports
+more than 32,000 subdirectories per directory, such as ReiserFS.
+(This doesn’t solve the <literal>st_nlink</literal> limit, but
+ReiserFS lies to the kernel by reporting a link count of 1 if it
+exceeds the limit.)</para>
+
+</section>
+  
+
+
+</appendix>