We have a new wiki. The migration is not 100% complete. You can help out by moving pages across. This wiki will exist for as long as there are pages left.

The official documentation has moved to http://docs.couchdb.org — The transition is not 100% complete, but http://docs.couchdb.org should be seen as having the latest info. In some cases, the wiki still has some more or older info on certain topics inside CouchDB.

You need to be added to the ContributorsGroup to edit the wiki. But don't worry! Just email any Mailing List or grab us on IRC and let us know your user name.

First Install

If your couch doesn't start after you've just installed, check the following things:

## what version of erlang are you running? R14B01 or R14B04 are well-known stable releases
erl -noshell -eval 'io:put_chars(erlang:system_info(otp_release)).' -s erlang halt
## are the erlang crypto (SSL) libraries working?
erl -noshell -eval 'case application:load(crypto) of ok -> io:put_chars("yay_crypto\n") ; _ -> exit(no_crypto) end.' -s init stop

## from an OSX homebrew install:
-env ERL_LIBS $ERL_LIBS:/usr/local/Cellar/couchdb/1.3.x/lib/couchdb/erlang/lib ...
## from a Centos6 install"
-env ERL_LIBS /usr/lib64/erlang/lib ...

erl -env ERL_LIBS $ERL_LIBS:/usr/local/Cellar/couchdb/1.3.x/lib/couchdb/erlang/lib -couch_ini -s crypto

%% test SSL support. If this fails, ensure you have the OTP erlang-crypto library installed

%% test Snappy compression. If this fails, check your CouchDB configure script output or alternatively
%% if your distro comes with erlang-snappy make sure you're using only the CouchDB supplied version

%% test the CouchDB JSON encoder. CouchDB uses different encoders in each release, this one matches
%% what is used in 1.2.x and 1.3.x.

%% this is how you quit the erlang shell.

Erlang R16B (erts-5.10.1) [source] [64-bit] [smp:8:8] [async-threads:10] [hipe] [kernel-poll:false] [dtrace]

Eshell V5.10.1  (abort with ^G)
1> crypto:md5_init().
2> snappy:compress("gogogogogogogogogogogogogogo").
3> ejson:decode(ejson:encode(<<"[1,2,3,4,5]">>)).

At this point the only remaining dependency is your systems' unicode support library, ICU, and the Spidermonkey Javascript VM from Mozilla. Make sure that your LD_LIBRARY_PATH or similar for non-Linux systems makes these available to CouchDB.

If you are still not able to get CouchDB to start, please put the output of the following on a paste service somewhere and contact the developers on IRC or the user email list. Replace ERL_LIBS as required. The output should resemble this.

erl -env ERL_LIBS $ERL_LIBS:/usr/local/Cellar/couchdb/1.3.x/lib/couchdb/erlang/lib -couch_ini -init_debug -emu_args -smp auto +W i +v -s couch


Built CouchDB directly from the Git repository?

Did you do a git pull that seemed to break everything?

After every update to the source, you must run the following command:


First Run

Having problems getting CouchDB to run for the first time?

Follow this simple procedure and report back to mailing list (or IRC) with the output of each step.

  1. Note down the name of your operating system and your processor architecture.
  2. Note down the installed versions of CouchDB's dependancies.
  3. Follow the checkout instructions to get a fresh copy of trunk.
  4. Bootstrap from the couchdb directory:

    • ./bootstrap

      FreeBSD users: if you get "aclocal: not found" you need to install automake.

  5. Build into a temporary directory:
    • ./configure --prefix=/tmp/couchdb && make && make install

      FreeBSD users: if you get "Syntax error: end of file unexpected" when you run make, you need to run gmake instead.

  6. Run the couchdb command and log the output:
    • /tmp/couchdb/bin/couchdb
  7. Use your system's kernel trace tool and log the output of the above command.
    1. Linux systems should use strace:
      • strace /tmp/couchdb/bin/couchdb 2> strace.out
    2. Please add documentation for your system...
  8. Report back to the mailing list (or IRC) with the output from each step.

Miscellaneous errors

CouchDB using a lot of memory (several hundred MB) on startup? This one seems to especially affect Dreamhost installs. It's really an issue with the Erlang VM pre-allocating data structures when ulimit is very large or unlimited. A detailed dicussion can be found on the erlang-questions list, but the short answer is that you should decrease ulimit -n or define ERL_MAX_PORTS to something reasonable like 1024.

Erlang backtraces are quite "hard" to read for non-Erlangers. The list here tries to give keywords to help you pinpointing your problem and suggests possible solutions

system_limit, erlang, open_port
Erlang has a default limit of 1024 ports, where each FD, tcp connection, and linked-in driver uses one port. You seem to have exceeded this. You can change it at runtime using the ERL_MAX_PORTS env variable.

(by Adam Kocoloski, https://bugs.edge.launchpad.net/ubuntu/+source/couchdb/+bug/459241)

Segmentation faults and bus errors

If CouchDB is crashing intermittently with a segmentation fault or a bus error, there's a good chance that OpenSSL is to blame. Mac OS X Lion ships with a version of OpenSSL that deprecates various functions used by OTP's crypto NIF. If this is the case, follow the steps below to fix the problem.

Get an older OpenSSL, for example:

Extract the tarball and build OpenSSL like this:

./Configure --prefix=/Users/fdmanana/my-openssl  darwin64-x86_64-cc
make test
make install

Then build Erlang OTP like this:

CC=gcc-4.2 CXX=g++-4.2 ./configure --prefix=/opt/otp-dev --enable-darwin-64bit --with-ssl=/Users/fdmanana/my-openssl
make install

Test your erl:

gert@couchdb:~$ erl
Erlang R16B (erts-5.10) [source] [64-bit] [smp:8:8] [async-threads:0] [hipe] [kernel-poll:false]

Eshell V5.10  (abort with ^G)
1> application:start(crypto).         
2> q().

Map/Reduce debugging

You can debug your Map and Reduce functions in the js command line. The fact that documents and function definitions are real javascript code makes it trivial to copy and paste both into SpiderMonkey.

First you assign a document to a variable. I like to copy from the Source tab of a doc in Futon:

js> doc = {
   "_id": "image-5",
   "_rev": "3-3e1b61291d9102d84e71e27cb46266fc",
   "status": 200,
   "style": "original"
[object Object]

Next you assign your function to another variable. Again I like to copy from the Source tab of a design doc in Futon:

js> map = function(doc) { emit(doc.style, doc) }
function (doc) {
    emit(doc.style, doc);

Don't forget to define the emit function as well. I just alias the print function:

js> emit = print
function print() {
    [native code]

Now you can manually apply your map function to this document, and see what gets emitted:

js> map(doc)
original [object Object]

From here, just keep redefining map and applying it to doc until you are emitting the desired output.

Troubleshooting (last edited 2013-03-22 20:17:57 by Peter Vogel)