Differences between revisions 27 and 28
Revision 27 as of 2013-03-22 20:17:57
Size: 8212
Editor: Peter Vogel
Comment: Link to erlang Forum is broken
Revision 28 as of 2016-08-27 08:05:06
Size: 179
Editor: JoanTouzet
Comment: Remove antequated and misleading information, point to the official documentation
Deletions are marked like this. Additions are marked like this.
Line 3: Line 3:
<<TableOfContents()>> = Troubleshooting =
Line 5: Line 5:
= First Install =

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

 * Usually this is a permissions issue. Ensure that you've followed the [[https://github.com/apache/couchdb/tree/master/INSTALL.Unix|chmod/chown steps in INSTALL.Unix]] tweaked for your platform
 * This means that the user that couchdb runs under has read/write for {{{.../var/{run,log,lib}/couchdb/}}} and {{{.../etc/couchdb}}} and their subdirectories, and read for Erlang, ICU, Spidermonkey & related libraries
 * For your distribution check that you *really* installed all the required Erlang modules. This varies from platform to platform so you'll just have to work it out the hard way.
 * Confirm that Erlang itself starts up, with crypto (SSL) support:
## 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
 * Next identify where your Erlang CouchDB libraries are installed. Usually that's as simple as tweaking the output of {{{grep ERL_LIBS `which couchdb`}}} as follows:
## 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 ...
 * Use this to start up Erlang with the CouchDB libraries in its path:
erl -env ERL_LIBS $ERL_LIBS:/usr/local/Cellar/couchdb/1.3.x/lib/couchdb/erlang/lib -couch_ini -s crypto
 * In that erlang shell, let's check that the key libraries are running. The %% lines are comments so you can skip them:
%% 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.

 * The output should resemble this, or an error will be thrown:
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 [[ErlInitDebug|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

= Upgrade =

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:


  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:


 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.
This content has been migrated to the [[http://docs.couchdb.org/en/latest/install/index.html|official CouchDB documentation]].

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.


This content has been migrated to the official CouchDB documentation.

Troubleshooting (last edited 2016-08-27 08:05:06 by JoanTouzet)