A few simple debugging tips for RTKLIB

Unfortunately, error reporting is not one of RTKLIB’s strengths.  Sometimes it will halt with an error message that is less than helpful, other times it will just continue through the entire solution with Q=0 or Q=2 without ever getting a fix because of a minor error in the input file configuration or parameters. I suspect anyone who has used RTKLIB with any regularity has run into cases like this innumerable times. It still happens to me all the time, almost always because I have made a silly mistake somewhere. For a new RTKLIB user, it can be quite difficult to figure out why they are not getting a valid solution in cases like this.

In this post, I will demonstrate some examples of common errors and some techniques to help identify them. First let’s take a quick look at a couple of real-time solution examples with RTKNAVI, then I will jump to post-processing cases for the rest of the examples.

In my experience, the most common error when using RTKNAVI is to improperly specify the base location. To demonstrate this, I go to the “Positions” tab on the “Options” menu in RTKNAVI and switch the Base Station position type from “Average of Single Position” to “RTCM Position”. In this example, my base stream is u-blox binary and contains no RTCM messages so RTKLIB will not get any valid base location information and can not calculate a solution. However, rather than halting and letting the user know there is a problem, RTKNAVI just runs through the whole solution without ever reporting either an error or a valid position. To help understand what happened in a case like this, the first step is to click on the tiny unlabeled square above the “Start/Stop” button. This will bring up the RTK Monitor window. Choose “Error/Warning” from the Monitor options as shown in the image below to bring up additional error and warning information.

In this case, every sample reports an “initial base station position error”. This should be enough information to track down the problem fairly quickly. Often this will be the case. If the additional information in this window doesn’t help, then the next step is to enable the debug trace and look at the trace file. This is covered in more detail in the post-processing examples further below.

In my experience, the second most common reason to get no solution with RTKNAVI is that navigation messages haven’t been enabled for either base or rover receiver. If this is the case, then all the SNR bars will be gray. When navigation data is available, the bars will be colored as in the image above. Lack of SNR bar color is the easiest way to detect this problem but another symptom is that the “Error/Warning” window will report “No common satellites” for every sample even though satellites are appearing in the SNR window.

A more general troubleshooting technique that will work for either real-time or post-processing and for GUI or command line RTKLIB applications is the debug trace file. I will demonstrate a couple of examples of using this with RTKPOST but the same basic technique can also be used with RTKNAVI, RNX2RTKOP, RTKCONV, CONVBIN, or STRSVR.

To enable the debug trace, set “Output Debug Trace” in the “Options” menu to something other than “OFF”. For simple errors, level 2 is enough and will produce a less overwhelming amount of information. For more detailed information about the GNSS solution, especially the ambiguity resolution, level 3 is better. For more details about the communication streams, level 4 can be useful. Level 5 includes many of the solution matrices and is too detailed for most general debug. Level 1 only contains the error messages available in the error window and is not useful. The image below from the RTKPOST Options menu shows the trace level set to 3. I usually set it to level 3 since I am often looking at the details of the ambiguity resolution, but for simple debug I would recommend starting with level 2 and that is what I will use in the examples below.

Next, I will intentionally make some silly mistakes and show how they appear in the error window and the trace file.

Let’s start with an example where RTKPOST actually does a good job of reporting the error to demonstrate how it should work, and occasionally does. To keep the example simple I will use files in the root directory, with names: rover.obs, base.obs, and rover.nav.

In this first case, I have made a typo in the name of the .nav file. Now, when I click on “Execute” to start the solution, it almost immediately halts and reports “Error: no nav data” in the error window near the bottom of the window. If only RTKLIB would always be as straightforward as this!

Next, I intentionally make a typo in the rover observation file and click on “Execute”. Again, the solution halts almost immediately but in this case the error message in the error window is much less useful. Not only does it not tell me which file has a problem, but it also suggests there is something specific wrong with the input data, not that the file is completely missing. Fortunately, clicking on another tiny unlabeled square (circled in red below) brings up the trace file, assuming trace debug was enabled as described above. This tells us exactly what went wrong, that the input rover observation file could not be opened.

For the next example, I will correct the typo in the file name but then set the location in the base rinex file header to all zeros. This is another common problem and usually happens because the rinex file was generated by RTKCONV or other application from a binary receiver output file that did not contain navigation messages. Without navigation information, RTKCONV can not estimate the receiver location and sets the approximate position field in the rinex header to all zeros. Again, the solution halts almost immediately, and the error message is identical to the previous case. However, looking at the trace file, there is now no mention of a file open error. To understand the difference between these two trace files, it’s important to know that the entries in the trace file beginning with 2 are warnings, and those beginning with 1 are errors. RTKLIB treats the missing file as a warning since there may be other observation files that are present, and doesn’t get an actual error until it looks for the base position information. With just the error, it is impossible to tell these two case apart, but by looking at the warnings as well, it is fairly easy to differentiate them.

Another fairly common error is to use the wrong base observation file. If the base observations do not overlap the rover observations in time, then the solution will run all the way through the data, without error, but the solution status will always be Q=0. Here’s the trace output for this example. I aborted the run before it completed, after it was obvious that something is wrong which is why the error windows shows “aborted”. The “age of differential” is the time between rover observation and closest base observation so again in this case, looking at the trace file makes the problem much more obvious

If the wrong navigation file is used, the solution will again run to the end with no error, and the status will remain Q=0, just as above, but this time the trace file will report “no common satellites”

Another mistake I make fairly often, is when I am specifying the precise base location rather than using the approximate location in the rinex header, and I forget to change it when moving to a different data set with a different base location. In this case, the solution will run without error, but the fix status will remain in float (Q=2) for the entire solution. There are several reasons why you might never get a fix, including just poor quality data, but in this case when I look at the trace file I see extremely large outliers right from the first sample. If all the satellites are reporting outliers and they are as large as this, that almost always means that the base location has been specified incorrectly.

These are only a few examples but probably cover over 80% of cases I look at where people are unable to get a solution. Most of the rest are caused by low quality data.

If you have other examples of common failures that I haven’t covered here, please describe them in a comment, along with the signature seen in the trace file.


12 thoughts on “A few simple debugging tips for RTKLIB”

  1. Tim
    A bit confused about antenna height. In Topcon Tools, you just select from a drop down box for the correct antenna name/brand and then input vertical or slant antenna height. In RTKlib:
    1. Where do you get the antenna parameters NGS08.atx? or IGS08.atx? Sokkia antennae are available in the NGS08.atx but not in the IGS08.atx.
    2. Will RTKlib read the antenna parameters from the atx file automatically? Is there a way to verify that it read the correct antenna parameter from the results file?
    3. What do I input into the U box? slant or vertical height?


    1. Hi Jun. Entering antenna type and offsets in RTKLIB can be a little confusing and is not well documented. You first need to specify the file that contains the calibration data in the Options/Files tab. You can use the igs14.atx file that is included with the demo5 executables. Antenna type and offsets are often specified in the header of the rinex observation file. If you want to use these values, set the “Antenna Type” field in the Options/Positions tab to “*”. If you want to manually specify antenna type AND offsets you can do that with the “Antenna Type” and “Delta-E/N/U” fields. The correct values for the Delta-E/N/U fields are simply the East, North, and Up offsets in meters for the antenna. Be aware that you can only use the antenna type and offsets from the rinex header or from the configuration values, RTKLIB never combines values from both.


      1. Thank you Tim,
        I am trying out the different options in RTKLib by comparing the results with what I get from Topcon & Spectra post processing software. Even the 2 results from Topcon & Spectra are different although in the cm level.
        Strange that I get the closest results when using sp3 files in RTKLib to N files in Topcon/Spectra results.


  2. Hi Tim
    Just downloaded the latest RTKLib and currently reviewing the various functions. I have been using GNSS Solutions for my post-processing and was trying to compare the results from the 2 software. I would like to ask a few questions:
    1. Using the same RINEX files, I am getting a fix solution (static) from GNSS Solutions but RTKLib I am getting a large file with individual second results. Most of which have the Q:4 solution. Shouldn’t I be getting just 1 lat/long/height solution?

    Where do you input the antenna height? I saw the the Options/Positions window with the Delta E/N/U boxes. The antenna height should go into the U box?

    Thank you.


    1. Hi Jun. A Q=4 solution is a DGPS solution. You must have the solution mode set to “dgps” instead of “kinematic”, meaning you are using pseudorange measurements only, no carrier phase. I would only recommend this for very poor quality data where the carrier phase measurements have so many cycle slips that they are degrading the solution. Yes, the antenna height should go into the Delta U box.


  3. Hi Tim,

    Congratulation for your web site, advices, codes …. I’ve used it, tested it on pc and RpiZeroW
    I’m located in North of France and want to use rtklib + 2 * neo m8t in real time calculation
    for agricultural driving purposes.

    Actual configuration is :
    Base on top of house (with ground plane):
    Hardware : neo m8t (CSG Shop) + ublox magnetic antenna ($20) + 433 MHz uhf transceiver
    Software : RawX + Sfrbx messages at a rate of 1 Hz

    Rover on top of tractor cab :
    Hardware : neo m8t + ublox magnetic antenna ($20) + uhf receiver + RpiZeroW
    Software : RpiZeroW with RTKRCV 2.4.3 (messages rate of 5 Hz) + the configuration file you provided for RTKRCV

    For debugging I use RtkNavi 2.4.3 demo b29d on PC and have tested all the points you’ve mentioned above
    I’ve roughly the same results on Rpi and on the PC (with the same .conf file) Good point …

    My system is “working”, it’s possible but difficult to have a fix, and more, to maintain it for a long time
    most of the time it’s float and the location is slightly always shifting.
    When the sky is very clear, it’s more easy to have fix.
    UHF link is stable and the base messages are comming OK in the Rpi
    In RtkNavi I’ve 7 to 10 satellites (green) between 40 and 50 db in Rover and Base frame
    The message error in RtkNavi is almost always “ambiguity validation failed” with 9 to 12 satellites, and ratio 1 to 1.5

    I’ve explored a lot things, configurations and tested all your advice but the result stays roughly at same level.
    I think of the following things, and at last I’ve post a question on your blog :
    Can it comes from my antennas, will it be much better with Tallysman or other dedicated rtk antenna ?
    Is there some specific setting for Europe in Ublox module or in RtkRcv I’ve not set ?
    Maybe there is another point I’ve forgotten ?
    Could it be much better if I move to zed f9p with dual band antenna at both sides ?

    If someone have roughly the same configuration in Europe, I’m interested to know if the results are better ?
    Any help appreciated
    If you need pictures of the system, don’t hesitate to ask me
    Best regards from France


    1. Hi Francois. Two M8T receivers with open sky views should be giving you a high percent of fix if you have RTKLIB set up correctly. The only setting you should need to change for Europe is to disable the SBAS constellation since the EGNOS satellites will degrade the solution. Make sure you have the GPS, Glonass, and Galileo constellation enabled on both base and rover and Glonass ambiguity resolution set to on since you have matched receivers. Also be sure you are using ground planes with both antennas. Higher quality antennas will improve the solution. You will see an even bigger improvement with the F9P, but of course the cost it a fair bit higher as well.


  4. Hi Tim, nice post, I will try the debug level setting to help with fine tuning of the processing parameters.
    Is there a way to set the output debug trace level in the conf file? I see ‘out-outstat’ to set off;state;residual and ‘file-tracefile’ presumably to override the default trace file path, but nothing that refers to the debug trace level.


    1. Hi Max. I don’t believe there is an option in the config file to set the debug trace level but it can be set as a command line option for both RNX2RTKP (-x) and RTKRCV (-t). For example to set it to 2 in RNX2RTKP, add “-x 2” to the command line.


Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.