Appendix B. Troubleshooting

Table of Contents

Common Problems
Problems Using Subversion
Every time I try to access my repository, my Subversion client just hangs.
Every time I try to run svn, it says my working copy is locked.
I'm getting errors finding or opening a repository, but I know my repository URL is correct.
How can I specify a Windows drive letter in a file:// URL?
I'm having trouble doing write operations to a Subversion repository over a network.
Under Windows XP, the Subversion server sometimes seems to send out corrupted data.
What is the best method of doing a network trace of the conversation between a Subversion client and Apache server?
I just built the distribution binary, and when I try to check out Subversion, I get an error about an Unrecognized URL scheme.
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.
When I start Apache, mod_dav_svn complains about a bad database version, that it found db-3.X, rather than db-4.X.
I'm getting Function not implemented errors on RedHat 9, and nothing works. How do I fix this?
Why does log say (no author) for files committed or imported via Apache (ra_dav)?
I'm getting occasional Access Denied errors on Windows. They seem to happen at random.
On FreeBSD, certain operations (especially svnadmin create) sometimes hang.
I can see my repository in a web browser, but svn checkout gives me an error about 301 Moved Permanently.
I'm trying to look at an old version of my file, but svn says something about path not found.

Common Problems

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).

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 with a detailed description of the problem you're having. [45]

Problems Using Subversion

Here are some of the most popular questions from Subversion's FAQ.

Every time I try to access my repository, my Subversion client just hangs.

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 file:// 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 lock file is left behind, along with a log file describing unfinished business. Any other process that attempts to access the database will just hang, waiting for the lock file 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.

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.

Simply run:

$ svnadmin recover /path/to/repos

Once the command has completed, check the permissions in the db/ directory of the repository.

Every time I try to run svn, it says my working copy is locked.

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 svn is interrupted while performing an action, then one or more lock files are left behind, along with log files describing the unfinished actions. (svn status will show an L next to locked directories.)

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:

$ svn cleanup

I'm getting errors finding or opening a repository, but I know my repository URL is correct.

See the section called “Every time I try to access my repository, my Subversion client just hangs.”.

You might also have a permissions problem opening the repository. See the section called “Supporting Multiple Repository Access Methods”.

How can I specify a Windows drive letter in a file:// URL?

See Repository URLs.

I'm having trouble doing write operations to a Subversion repository over a network.

If import works fine over local access:

$ mkdir test
$ touch test/testfile
$ svn import test file:///var/svn/test -m "Initial import"
Adding         test/testfile
Transmitting file data .
Committed revision 1.

But not from a remote host:

$ svn import test http://svn.red-bean.com/test -m "Initial import"
harry's password: xxxxxxx

svn_error: … The specified activity does not exist.

We've seen this when the REPOS/dav/ directory is not writable by the httpd process. Check the permissions to ensure that Apache httpd can write to the dav/ directory (and to the corresponding db/ directory, of course).

Under Windows XP, the Subversion server sometimes seems to send out corrupted data.

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 http://support.microsoft.com/default.aspx?scid=kb;EN-US;q317949.

What is the best method of doing a network trace of the conversation between a Subversion client and Apache server?

Use Ethereal to eavesdrop on the conversation:

Note

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 tethereal).

  • Pull down the Capture menu, and choose Start.

  • Type port 80 for Filter, and turn off promiscuous mode.

  • Run your Subversion client.

  • Hit Stop. Now you have a capture. It looks like a huge list of lines.

  • Click on the Protocol column to sort.

  • Then, click on the first relevant TCP line to select it.

  • Right click, and choose Follow TCP Stream. You'll be presented with the request/response pairs of the Subversion client's HTTP conversion.

Alternatively, you may set a parameter in your client's servers run-time configuration file to cause Neon's debugging output to appear. The numeric value of neon-debug is a combination of the NE_DBG_* values in the header file ne_utils.h. Setting the neon-debug-mask variable to 130 (i.e. NE_DBG_HTTP + NE_DBG_HTTPBODY) will cause the HTTP data to be shown.

You may well want to disable compression when doing a network trace by tweaking the http-compression parameter in the same file.

I just built the distribution binary, and when I try to check out Subversion, I get an error about an “Unrecognized URL scheme.

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 file:// URL will try to load ra_local, and an http:// URL will try to load ra_dav.

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 /etc/ld.so.conf 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.

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.

The short answer: it's for your own good.

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.

Making the svn revert command require an explicit target—even if that target is just “.”—is one way of accomplishing that. This requirement (as well as requiring you to supply the --recursive 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.

When I start Apache, mod_dav_svn complains about a “bad database version”, that it found db-3.X, rather than db-4.X.

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.

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".

I'm getting “Function not implemented” errors on RedHat 9, and nothing works. How do I fix this?

This is not really a problem with Subversion, but it often affects Subversion users.

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:

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

This can be fixed in one of several ways:

  • Rebuild db4 for the kernel you're using.

  • Use a RedHat 9 kernel.

  • Apply the NPTL patches to the kernel you're using.

  • Use a recent (2.5.x) kernel with the NPTL support included.

  • Check if environment variable LD_ASSUME_KERNEL 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)

Why does log say “(no author)” for files committed or imported via Apache (ra_dav)?

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:

$ svn log
------------------------------------------------------------------------
rev 24:  (no author) | 2003-07-29 19:28:35 +0200 (Tue, 29 Jul 2003)
…

Read about adding authentication in Chapter 6, Server Configuration.

I'm getting occasional “Access Denied” errors on Windows. They seem to happen at random.

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 http://www.contactor.se/~dast/svn/archive-2003-10/0136.shtml. A workaround that should reduce the incidence rate for most people was implemented in revision 7598.

On FreeBSD, certain operations (especially svnadmin create) sometimes hang.

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 random(4) and rndcontrol(8) on how to effect this change. Another workaround is to compile APR against /dev/urandom instead of /dev/random.

I can see my repository in a web browser, but svn checkout gives me an error about 301 Moved Permanently.

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.

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

The solution is to make sure your repository <Location> does not overlap or live within any areas already exported as normal web shares.

I'm trying to look at an old version of my file, but svn says something about “path not found”.

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

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

Unfortunately, while the repository is aware of copies and renames, almost all the svn client subcommands in version 1.0 are not aware. Commands like svn diff, svn merge, and svn cat 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 svn diff to compare two earlier versions of /branches/mybranch/foo.c, the command will not automatically understand that the task actually requires comparing two versions of /trunk/foo.c, due to the rename. Instead, you'll see an error about how the branch-path doesn't exist in the earlier revisions.

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

$ 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

...you would instead run

$ svn diff -r1000:2000 http://host/repos/trunk/foo.c
...


[45] 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.