This page is mostly a place holder to be filled out as common problems are noticed. If you see someone pop up on IRC confused, and a few helpful comments get them straightened out, please jot them down here. To help us kee how bad problems are, add an "x" where noted if a hint helps you out.

Patches to make these hints unnecessary -- either to the manual or the code -- would be wonderful.

Runtime Problems

I get a segfault every time I run mtn

This almost always turns out to be the result of mismatched C++ libraries. The common cause of this is that your mtn binary and the Boost libraries monotone uses on were built using different versions of the C++ compiler and ended up linked against different versions of libstdc++.

Check for this using ldd

ldd /path/to/mtn | grep 'stdc++' => /usr/lib/gcc/i686-pc-linux-gnu/3.4.6/ (0xb7aae000) => /usr/lib/gcc/i686-pc-linux-gnu/3.4.6/ (0xb7d32000)

In this example, mtn had been freshly built, but Boost had not been rebuilt since a compiler upgrade. This caused mtn to be linked against when the Boost libraries were still linked against Rebuilding Boost was the solution in this case.

Client/Server Problems

I get usage information when attempting to sync over ssh

This will happen if the remote host is running an older version of monotone. This is because the specification of a branch pattern to serve was dropped from the mtn serve command in recent versions. This can be fixed by modifying the get_netsync_connect_command hook to execute the remote mtn process with '*' as the branch pattern. The following modified hook can be placed your monotonerc file (probably in _MTN/monotonerc), to resolve this issue.

function get_netsync_connect_command(uri, args)

    local argv = nil

    if uri["scheme"] == "ssh"
        and uri["host"]
        and uri["path"] then

        argv = { "ssh" }
        if uri["user"] then
            table.insert(argv, "-l")
            table.insert(argv, uri["user"])
        if uri["port"] then
            table.insert(argv, "-p")
            table.insert(argv, uri["port"])

        table.insert(argv, uri["host"])

    if uri["scheme"] == "file" and uri["path"] then
        argv = { }

    if argv then

        table.insert(argv, get_mtn_command(uri["host"]))

        if args["debug"] then
            table.insert(argv, "--debug")
            table.insert(argv, "--quiet")

        table.insert(argv, "--db")
        table.insert(argv, uri["path"])
        table.insert(argv, "serve")
        table.insert(argv, "*")
        table.insert(argv, "--stdio")
        table.insert(argv, "--no-transport-auth")

        if args["include"] then
            table.insert(argv, args["include"])

        if args["exclude"] then
            table.insert(argv, "--exclude")
            table.insert(argv, args["exclude"])
    return argv

Check Your Quoting

On Windows

mtn sync 'mybranch'

does not find a branch named mybranch, but

mtn sync "mybranch"


Also on Windows, glob expansion can be rather funky, e.g.

mtn sync '*'


mtn sync "*"

...will both undergo glob expansion, resulting in a command-line which contains a list of files in the current directory. To get around this, use

mtn sync "{}*"

Add an 'x' here if this helped you: x

Check your permissions

A bug in monotone right now is that it does a lousy job of giving feedback when your permissions are set up wrong -- usually the server will just drop your connection, instead of sending you a message explaining why. If your new server does not appear to be accepting your connections try:

  • checking the server log for any notes about permissions
  • make sure your read permission file is correct -- it is in a simple little language that looks like:

    pattern "*"
    allow ""
    allow ""

    to allow Abe and Beth read access to all branches, or

    pattern "foo*"
    allow "*"

    to allow anonymous access to all branches whose names begin "foo".

  • make sure your write permission file is correct -- it is not the same format as the read permission file, because write permissions are per-db, while read permissions are per-branch. (This has to do with the somewhat amorphous nature of monotone branches.) A write permissions file might look like

Add an 'x' here if this helped you:


Other Categories?

Please edit this page if you have tips to share.

mtn: error: sqlite error: database is locked

Be sure that another mtn process is not accessing the database:

  • ps -efww | grep mtn ## OR
  • lsof | fgrep

Even a mtn serve background server will lock the database, preventing all access.

"But I'm sure there is no such process!!"

If your database is on NFS or some network filesystem (not recommended), it may falsely report a stale lock. In this case, you can try:

cp <>
diff <> && mv <>

Recovering from database errors

See the "Database" section of the manual for more info on the mtn db ... commands

TODO: include some sample errors and and fixing commands.

warning: mismatched certs

For example:

mtn: revision 0c8d244e3a2db6cae8be75aa8b269c6f5d70f6d4 mismatched certs (1 authors 2 dates 2 changelogs)
mtn: warning: 1 mismatched certs
mtn: check complete: 70679 files; 8777 rosters; 8777 revisions; 15 keys; 35677 certs; 8778 heights; 43 branches
mtn: total problems detected: 1 (0 serious)
mtn: minor problems detected

Recovery steps: * ???

mtn: fatal: error

For example:

mtn: fatal: error: ../ I(res.size() == 1)
mtn: this is almost certainly a bug in monotone.
mtn: please send this error message, the output of 'mtn version --full',
mtn: and a description of what you were doing to
mtn: wrote debugging log to /Users/douglasdd/.monotone/dump
mtn: if reporting a bug, please include this file

Recovery Steps: * ???? with luck the developers who respond will have some suggestions for you.

Docs are unclear for mtn db load

The docs say

...the schema of the dumped database is included in the dump, so you should not try to init your database before a load.

OK, fine, but how do you create a database without init?

Quick Links:    -     Downloads    -     Documentation    -     Wiki    -     Code Forge    -     Build Status