appb.xml - svnbook - Project Hosting on Google Code

‹r1121

r3653

Source path: svn/ tags/ en-1.0-final/ src/ book/ book/ appb.xml

  <appendix id="svn-ap-b">
    <title>Troubleshooting</title>

  <!-- ================================================================= -->
  <!-- ======================== SECTION 1 ============================== -->
  <!-- ================================================================= -->
  <sect1 id="svn-ap-b-sect-1">
    <title>Common Problems</title>
    
    <para>There are a number of problems you may run into in the
      course of installing and using Subversion.  Some of these will
      be resolved once you get a better idea of how Subversion does
      things, while others are caused because you're used to the way
      that other version control systems work.  Still other problems
      might be unsolvable due to bugs in some of the operating systems
      that Subversion runs on (considering the wide array of OS'es
      that Subversion runs on, it's amazing that we don't encounter
      many more of these).</para>

    <para>The following list has been compiled over the course of
      years of Subversion usage.  If you can't find the problem you're
      having here, look at the most up-to-date version of the FAQ on
      Subversion's main website.  If you're still stuck, then send
      mail to <email>users@subversion.tigris.org</email> with a
      detailed description of the problem you're having.
      <footnote><para>Remember that the amount of detail you provide
      about your setup and your problem is directly proportional to
      the likelihood of getting an answer from the mailing list.
      You're encouraged to include everything short of what you had
      for breakfast and your mother's maiden name.  </para>
      </footnote> </para>
      
  
    <sect2 id="svn-ap-b-sect-1.2">
      <title>Problems Using Subversion</title>
      
      <para>Here are some of the most popular questions from
        Subversion's FAQ.</para>

      <sect3 id="svn-ap-b-sect-1.2.1">
        <title>Every time I try to access my repository, my Subversion
          client just hangs.</title>
        
        <para>Your repository is not corrupt, nor is your data
          lost. If your process accesses the repository directly
          (mod_dav_svn, svnlook, svnadmin, or if you access a
          <literal>file://</literal> URL), then it's using Berkeley DB to
          access your data.  Berkeley DB is a journaling system, meaning
          that it logs everything it is about to do before it does so.  If
          your process is interrupted (e.g. by a kill signal or segfault),
          then a lockfile is left behind, along with a logfile describing
          unfinished business.  Any other process that attempts to
          access the database will just hang, waiting for the lockfile
          to disappear.  To awaken your repository, you need to ask
          Berkeley DB to either finish the work, or rewind the
          database to a previous state that is known to be
          consistent.</para>

        <para>Make sure you run this command as the user that owns and
          manages the database, not as root, or else it will leave
          root-owned files in the db directory.  These files cannot be opened
          by the non-root user that manages the database, which is
          typically either you or your Apache process.  Also be sure
          to have the correct umask set when you run recover, since
          failing to do so will lock out users that are in the group
          allowed to access the repository.</para>

        <para>Simply run:</para>

<screen>
$ svnadmin recover /path/to/repos
</screen>

        <para>Once the command has completed, check the permissions in the
          <filename>db/</filename> directory of the repository.</para>
        
      </sect3>
      
      
      <sect3 id="svn-ap-b-sect-1.2.2">
        <title>Every time I try to run <command>svn</command>, it
          says my working copy is locked.</title>
        
        <para>Subversion's working copy, just like Berkeley DB, uses a
          journaling mechanism to perform all actions. That is, it
          logs everything it is about to do before it does so. If
          <command>svn</command> is interrupted while performing an
          action, then one or more lockfiles are left behind, along
          with log files describing the unfinished
          actions. (<command>svn status</command> will show an
          <literal>L</literal> next to locked directories.)</para>
        
        <para>Any other process that attempts to access the working
          copy will fail when it sees the locks. To awaken your
          working copy, you need to tell the client to finish the
          work.  To fix this, run this command from the top of your
          working copy:</para>
        
        <screen>
$ svn cleanup
</screen>

      </sect3>

      
      <sect3 id="svn-ap-b-sect-1.2.3">
        <title>I'm getting errors finding or opening a repository,
          but I know my repository URL is correct.</title>

        <para>See <xref linkend="svn-ap-b-sect-1.2.1"/>.</para>

        <para>You might also have a permissions problem opening the
          repository.  See <xref linkend="svn-ch-6-sect-5"/>.</para>
      </sect3>

      
      <sect3 id="svn-ap-b-sect-1.2.4">
        <title>How can I specify a Windows drive letter in a
          <literal>file://</literal> URL?</title>
        
        <para>See <xref linkend="svn-ch-2-sidebar-1"/>.</para>
      </sect3>
      
      <sect3 id="svn-ap-b-sect-1.2.5">
        <title>I'm having trouble doing write operations to a
          Subversion repository over a network.</title>
        
        <para>If import works fine over local access:</para>
        
        <screen>
$ mkdir test
$ touch test/testfile
$ svn import test file:///var/svn/test -m "Initial import"
Adding         test/testfile
Transmitting file data .
Committed revision 1.
</screen>

        <para>But not from a remote host:</para>
        
        <screen>
$ svn import test http://svn.red-bean.com/test -m "Initial import"
harry's password: xxxxxxx

svn_error: &hellip; The specified activity does not exist.
</screen>
        
        <para>We've seen this when the <filename>REPOS/dav/</filename>
          directory is not writable by the httpd process. Check the
          permissions to ensure that Apache httpd can write to the
          <filename>dav/</filename> directory (and to the
          corresponding <filename>db/</filename> directory, of
          course).</para>
        
      </sect3>


      <sect3 id="svn-ap-b-sect-1.2.6">
        <title>Under Windows XP, the Subversion server sometimes
          seems to send out corrupted data.</title>
        
        <para>You need to install Windows XP Service Pack 1 to fix a
          TCP/IP stack bug in the operating system.  You can get all
          sorts of information about that Service Pack at <systemitem
          class="url">http://support.microsoft.com/default.aspx?scid=kb;EN-US;q317949</systemitem>.</para>
      </sect3>
      
      
      <sect3 id="svn-ap-b-sect-1.2.7">
        <title>What is the best method of doing a network trace of
          the conversation between a Subversion client and
          Apache server?</title>
        
        <para>Use Ethereal to eavesdrop on the conversation:</para>

        <note>
          <para>The following instructions are specific to the
            graphical version of Ethereal, and may not apply to the
            command line version (whose binary is usually named
            <command>tethereal</command>).</para>
        </note>
        
        <itemizedlist>
          <listitem>
            <para>Pull down the Capture menu, and choose
              Start.</para>
          </listitem>
          
          <listitem>
            <para>Type port 80 for Filter, and turn off promiscuous
              mode.</para>
          </listitem>
          
          <listitem>
            <para>Run your Subversion client.</para>
          </listitem>
          
          <listitem>
            <para>Hit Stop. Now you have a capture. It looks like a
              huge list of lines.</para>
          </listitem>
          
          <listitem>
            <para>Click on the Protocol column to sort.</para>
          </listitem>
          
          <listitem>
            <para>Then, click on the first relevant TCP line to
              select it.</para>
          </listitem>
          
          <listitem>
            <para>Right click, and choose Follow TCP Stream. You'll
              be presented with the request/response pairs of the
              Subversion client's HTTP conversion.</para>
          </listitem>
        </itemizedlist>
        
        <para>Alternatively, you may set a parameter in your client's
          <filename>servers</filename> run-time configuration file to
          cause neon's debugging output to appear.  The numeric value
          of neon-debug is a combination of the
          <literal>NE_DBG_*</literal> values in the header file
          <filename>ne_utils.h</filename>. Setting the
          <literal>neon-debug-mask</literal> variable to 130
          (i.e. <literal>NE_DBG_HTTP + NE_DBG_HTTPBODY</literal>) will
          cause the HTTP data to be shown.</para>


        <para>You may well want to disable compression when doing a
          network trace by tweaking the
          <literal>http-compression</literal> parameter in the same
          file.</para>
      </sect3>

      <sect3 id="svn-ap-b-sect-1.2.8">
        <title>I just built the distribution binary, and when I try to
          check out Subversion, I get an error about an "Unrecognized
          URL scheme."</title>
        
        <para>Subversion uses a plugin system to allow access to
          repositories.  Currently there are three of these plugins:
          ra_local allows access to a local repository, ra_dav
          allows access to a repository via WebDAV, and ra_svn allows
          local or remote access via the svnserve server.  When you
          attempt to perform an operation in subversion, the program
          tries to dynamically load a plugin based on the URL scheme.
          A <literal>file://</literal> URL will try to load ra_local,
          and an <literal>http://</literal> URL will try to load ra_dav.</para>

        <para>The error you are seeing means that the dynamic
          linker/loader can't find the plugins to load.  This normally
          happens when you build subversion with shared libraries,
          then attempt to run it without first running 'make install'.
          Another possible cause is that you ran make install, but the
          libraries were installed in a location that the dynamic
          linker/loader doesn't recognize.  Under Linux, you can allow
          the linker/loader to find the libraries by adding the
          library directory to <filename>/etc/ld.so.conf</filename>
          and running ldconfig.  If you don't wish to do this, or you
          don't have root access, you can also specify the library
          directory in the LD_LIBRARY_PATH environment
          variable.</para>
        </sect3>


      <sect3 id="svn-ap-b-sect-1.2.9">
        <title>Why does the 'svn revert' command require an explicit
          target? Why is it not recursive by default? This behavior
          differs from almost all the other subcommands.</title>

        <para>The short answer: it's for your own good.</para>

        <para>Subversion places a very high priority on protecting
          your data, and not just your versioned data.  Modifications
          that you make to already-versioned files, and new files
          scheduled for addition to the version control system, must
          be treated with care.</para>
        
        <para>Making the <command>svn revert</command> command require
          an explicit target&mdash;even if that target is just
          '.'&mdash;is one way of accomplishing that.  This
          requirement (as well as requiring you to supply the
          <option>--recursive</option> flag if you want that behavior)
          is intended to make you really think about what you're
          doing, because once your files are reverted, your local
          modifications are gone forever.</para>        
      </sect3>


      <sect3 id="svn-ap-b-sect-1.2.10">
        <title>When I start Apache, mod_dav_svn complains about a "bad
          database version", that it found db-3.X, rather than
          db-4.X.</title>

        <para>Your apr-util linked against DB-3, and svn linked
          against DB-4.  Unfortunately, the DB symbols aren't
          different.  When mod_dav_svn is loaded into Apache's
          process-space, it ends up resolving the symbol names against
          apr-util's DB-3 library.</para>

        <para>The solution is to make sure apr-util compiles against
          DB-4.  You can do this by passing specific switches to
          either apr-util's or apache's configure: "--with-dbm=db4
          --with-berkeley-db=/the/db/prefix".</para>
      </sect3>


      <sect3 id="svn-ap-b-sect-1.2.11">
        <title>I'm getting "Function not implemented" errors on RedHat
          9, and nothing works. How do I fix this?</title>

        <para>This is not really a problem with Subversion, but it often
          affects Subversion users.</para>

        <para>RedHat 9 and Fedora ship with a Berkeley DB library that
          relies on the kernel support for NPTL (the Native Posix
          Threads Library).  The kernels that RedHat provides have
          this support built in, but if you compile your own kernel,
          then you may well not have the NPTL support.  If that is the
          case, then you will see errors like this:</para>

<screen>
svn: Berkeley DB error
svn: Berkeley DB error while creating environment for filesystem tester/db:
Function not implemented
</screen>

        <para>This can be fixed in one of several ways:</para>

        <itemizedlist>
          <listitem><para>Rebuild db4 for the kernel you're
          using.</para></listitem>

          <listitem><para>Use a RedHat 9 kernel.</para></listitem>

          <listitem><para>Apply the NPTL patches to the kernel you're
              using.</para></listitem>

          <listitem><para>Use a recent (2.5.x) kernel with the NPTL support
              included.</para></listitem>

          <listitem><para>Check if environment variable
              <literal>LD_ASSUME_KERNEL</literal> is set to 2.2.5, and
              if so, unset it before starting Subversion
              (Apache). (You usually would set this variable to run
              Wine or Winex on RedHat 9)</para></listitem>
        </itemizedlist>          
      </sect3>


      <sect3 id="svn-ap-b-sect-1.2.12">
        <title>Why does log say "(no author)" for files committed
          or imported via Apache (ra_dav)?</title>

        <para>If you allow anonymous write access to the repository
          via Apache, the Apache server never challenges the client
          for a username, and instead permits the write operation
          without authentication.  Since Subversion has no idea who
          did the operation, this results in a log like this:</para>

<screen>
$ svn log
------------------------------------------------------------------------
rev 24:&nbsp; (no author) | 2003-07-29 19:28:35 +0200 (Tue, 29 Jul 2003)
&hellip;
</screen>

        <para>Read about adding authentication in <xref
            linkend="svn-ch-6"/>.</para>
      </sect3>


      <sect3 id="svn-ap-b-sect-1.2.13">
        <title>I'm getting occasional "Access Denied" errors on
          Windows.  They seem to happen at random.</title>

        <para>These appear to be due to the various Windows services
          that monitor the filesystem for changes (anti-virus
          software, indexing services, the COM+ Event Notification
          Service).  This is not really a bug in Subversion, which
          makes it difficult for to fix.  A summary of the current
          state of the investigation is available at <systemitem
          class="url">http://www.contactor.se/~dast/svn/archive-2003-10/0136.shtml</systemitem>.
          A workaround that should reduce the incidence rate for most
          people was implemented in revision 7598.</para>
      </sect3>


      <sect3 id="svn-ap-b-sect-1.2.14">
        <title>On FreeBSD, certain operations (especially svnadmin
          create) sometimes hang.</title>

        <para>This is usually due to a lack of available entropy on
          the system.  Subversion asks APR to generate random numbers
          to create UUIDs from time to time, and certain operating
          systems will block for high-quality randomness.  You
          probably need to configure the system to gather entropy from
          sources such as hard-disk and network interrupts.  Consult
          your system manpages, specifically
          <command>random(4)</command> and
          <command>rndcontrol(8)</command> on how to effect this
          change.  Another workaround is to compile APR against
          <filename>/dev/urandom</filename> instead of
          <filename>/dev/random</filename>.</para>
      </sect3>


      <sect3 id="svn-ap-b-sect-1.2.15">
        <title>I can see my repository in a web browser, but 'svn
          checkout' gives me an error about "301 Moved
          Permanently".</title> 

        <para>It means your httpd.conf is misconfigured.  Usually this
          error happens when you've defined the Subversion virtual
          "location" to exist within two different scopes at the same
          time.</para>

        <para>For example, if you've exported a repository as
            <literal>&lt;Location /www/foo&gt;</literal>, but you've
            also set your <literal>DocumentRoot</literal> to be
            <filename>/www</filename>, then you're in trouble.  When
            the request comes in for
            <filename>/www/foo/bar</filename>, apache doesn't know
            whether to find a <emphasis>real</emphasis> file named
            <filename>/foo/bar</filename> within your
            <literal>DocumentRoot</literal>, or whether to ask
            mod_dav_svn to fetch a file <filename>/bar</filename> from
            the <filename>/www/foo</filename> repository.  Usually the
            former case wins, and hence the "Moved Permanently"
            error.</para>


        <para>The solution is to make sure your repository
          <literal>&lt;Location&gt;</literal> does not overlap or live
          within any areas already exported as normal web
          shares.</para>
      </sect3>

      
      <sect3 id="svn-ap-b-sect-1.2.16">
        <title>I'm trying to look at an old version of my file, but svn
          says something about "path not found".</title>

        <para>A nice feature of Subversion is that the repository
          understands copies and renames, and preserves the historical
          connections.  For example, if you copy
          <filename>/trunk</filename> to
          <filename>/branches/mybranch</filename>, then the repository
          understands that every file in the branch has a
          "predecessor" in the trunk.  Running <filename>svn log
          --verbose</filename> will show you the historical copy, so
          you can see the rename:</para>

<screen>
r7932 | joe | 2003-12-03 17:54:02 -0600 (Wed, 03 Dec 2003) | 1 line
Changed paths:
   A /branches/mybranch (from /trunk:7931)
</screen>

        <para>Unfortunately, while the repository is aware of copies
          and renames, almost all the svn client subcommands in
          version 1.0 are <emphasis>not</emphasis> aware.  Commands
          like <command>svn diff</command>, <command>svn
          merge</command>, and <command>svn cat</command> ought to
          understand and follow renames, but don't yet do this.  It's
          scheduled as a post-1.0 feature.  For example, if you ask
          <command>svn diff</command> to compare two earlier versions
          of <filename>/branches/mybranch/foo.c</filename>, the
          command will not automatically understand that the task
          actually requires comparing two versions of
          <filename>/trunk/foo.c</filename>, due to the rename.
          Instead, you'll see an error about how the branch-path
          doesn't exist in the earlier revisions.</para>

        <para>The workaround for all problems of this sort is to do
          the legwork yourself.  That is: <emphasis>you</emphasis>
          need to be aware of any renamed paths, discover them
          yourself using <command>svn log -v</command>, and then
          provide them explicitly to the svn client.  For example,
          instead of running</para>

<screen>
$ svn diff -r 1000:2000 http://host/repos/branches/mybranch/foo.c
svn: Filesystem has no item
svn: '/branches/mybranch/foo.c' not found in the repository at revision 1000
</screen>

        <para>...you would instead run</para>

<screen>
$ svn diff -r1000:2000 http://host/repos/trunk/foo.c
...
</screen>
      </sect3>

      </sect2>

    </sect1>

</appendix>

<!--
local variables: 
sgml-parent-document: ("book.xml" "appendix")
end:
-->

Show details Hide details

Change log

r1122 by cmpilato on Feb 25, 2005 Diff

Rename tag to associate with English
version only.

Go to:

Older revisions

r1107 by sussman on Feb 23, 2005 Diff

Create 'book-1.0-final' tag.  This is
a snapshot of the last version
of the book's trunk before we started
documenting 1.1 features.

r612 by mthelen on Jun 11, 2004 Diff

Fix incorrect grammar and awkward
phrasing in the book.

* doc/book/book/appb.xml
  (svn-ap-b-sect-1.2.1): Insert a
...

r611 by mthelen on Jun 11, 2004 Diff

Fix small inconsistencies in command
line examples in the book.

* doc/book/book/appb.xml
  (svn-ap-b-sect-1.2.2): Change 'svn
...

All revisions of this file

File info

Size: 21320 bytes, 505 lines

View raw file

File properties

svn:mime-type: text/xml
svn:eol-style: native