Troubleshooting

This guide covers common problems encountered when building, configuring, and running ORB-SLAM3, with practical solutions.

Build Errors

Dependencies Not Found

OpenCV Not Found

Error Message:

CMake Error: Could not find OpenCV
FATAL_ERROR: OpenCV > 4.4 not found.

Solutions:

Install OpenCV (Ubuntu/Debian):

sudo apt update
sudo apt install libopencv-dev

Specify OpenCV path explicitly:

cmake .. -DOpenCV_DIR=/path/to/opencv/build

Check OpenCV version:
```
pkg-config --modversion opencv4
```
Required: OpenCV 3.2+ (tested with 3.2.0 and 4.4.0)

Build OpenCV from source if version is too old:

git clone https://github.com/opencv/opencv.git
cd opencv && mkdir build && cd build
cmake .. -DCMAKE_BUILD_TYPE=Release
make -j$(nproc)
sudo make install

Eigen3 Not Found

Error Message:

Could NOT find Eigen3 (missing: EIGEN3_INCLUDE_DIR)

Solutions:

Install Eigen3:
```
sudo apt install libeigen3-dev
```
Verify installation:
```
dpkg -L libeigen3-dev | grep eigen3.pc
```

Manually specify Eigen path:

cmake .. -DEIGEN3_INCLUDE_DIR=/usr/include/eigen3

Required version: Eigen 3.1.0+

Pangolin Not Found

Error Message:

Could NOT find Pangolin

Solutions:

Install Pangolin dependencies:

sudo apt install libglew-dev libgl1-mesa-dev libglu1-mesa-dev

Build Pangolin from source:

git clone https://github.com/stevenlovegrove/Pangolin.git
cd Pangolin
mkdir build && cd build
cmake ..
make -j$(nproc)
sudo make install

Update library cache:
```
sudo ldconfig
```

Third-Party Library Build Failures

DBoW2 Build Error

Error: DBoW2 compilation fails during build.shSolutions:

Clean and rebuild:

cd Thirdparty/DBoW2/build
rm -rf *
cmake .. -DCMAKE_BUILD_TYPE=Release
make -j4

Check for conflicting DBoW2 installations:

sudo apt remove ros-*-dbow2  # If using ROS

Verify library is created:

ls -lh Thirdparty/DBoW2/lib/libDBoW2.so

g2o Compilation Errors

Error: g2o fails to compile in Thirdparty/g2oSolutions:

Install missing dependencies:

sudo apt install libsuitesparse-dev qtdeclarative5-dev \
                 qt5-qmake libqglviewer-dev-qt5

Clean build directory:

cd Thirdparty/g2o/build
rm -rf *
cmake .. -DCMAKE_BUILD_TYPE=Release
make -j4

Check Eigen version compatibility: g2o requires Eigen3 3.1.0+

Sophus Build Issues

Error: Sophus compilation failsSolution:

Ensure C++11 support:
```
g++ --version  # Should be GCC 4.8+
```

Rebuild Sophus:

cd Thirdparty/Sophus/build
rm -rf *
cmake .. -DCMAKE_BUILD_TYPE=Release
make -j4

Linking Errors

Undefined Reference Errors

Error Message:

undefined reference to `ORB_SLAM3::System::System(...)`

Solutions:

Verify library is built:
```
ls -lh lib/libORB_SLAM3.so
```

Check library path:

export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/path/to/ORB_SLAM3/lib
sudo ldconfig

Rebuild from scratch:

cd build
rm -rf *
cmake .. -DCMAKE_BUILD_TYPE=Release
make -j4

Boost Serialization Not Found

Error Message:

cannot find -lboost_serialization

Solution:

# Install Boost serialization
sudo apt install libboost-serialization-dev

# Verify installation
ldconfig -p | grep boost_serialization

Python Development Headers Missing

Error Message:

Python.h: No such file or directory

Solutions:

Install Python development package:

# For Python 2.7
sudo apt install libpython2.7-dev

# For Python 3
sudo apt install libpython3-dev python3-numpy

Verify NumPy installation:

python3 -c "import numpy; print(numpy.__version__)"

Runtime Errors

Initialization Failures

Vocabulary Loading Error

Error Message:

Loading ORB Vocabulary. This could take a while...
Segmentation fault (core dumped)

Solutions:

Extract vocabulary file:

cd Vocabulary
tar -xf ORBvoc.txt.tar.gz
ls -lh ORBvoc.txt  # Should be ~50MB

Verify file path:

./Examples/Stereo/stereo_euroc \
    "$(pwd)/Vocabulary/ORBvoc.txt" \
    Examples/Stereo/EuRoC.yaml \
    /path/to/dataset

Check available memory:
```
free -h  # Need at least 2GB free RAM
```

Configuration File Error

Error Message:

Failed to open settings file at: config.yaml

Solutions:

Verify file exists:
```
ls -lh Examples/Stereo/EuRoC.yaml
```

Check YAML syntax:

# Install yamllint
pip install yamllint

# Validate syntax
yamllint Examples/Stereo/EuRoC.yaml

Common YAML issues:
- Tabs instead of spaces (use spaces only)
- Missing colons after parameter names
- Incorrect indentation

Camera Parameter Errors

Error Message:

Camera.fx required parameter does not exist, aborting...

Solutions:

Verify all required parameters are present:

Camera.type: "PinHole"
Camera1.fx: 458.654
Camera1.fy: 457.296
Camera1.cx: 367.215
Camera1.cy: 248.375
Camera.width: 752
Camera.height: 480

Check parameter names (case-sensitive):
- Use Camera1.fx, not camera1.fx
- Use ORBextractor.nFeatures, not ORBExtractor.nFeatures

Validate camera model:

Camera.type: "PinHole"     # Correct
# Camera.type: "Pinhole"  # Incorrect (wrong case)

Tracking Lost Scenarios

Immediate Tracking Loss

Symptoms: “Tracking lost” on first or second frameCauses & Solutions:

Incorrect camera parameters:
- Verify calibration is correct
- Check image resolution matches YAML
- Test with known-good configuration first

Insufficient features:

# Increase feature count
ORBextractor.nFeatures: 1500

# Reduce FAST threshold
ORBextractor.iniThFAST: 12
ORBextractor.minThFAST: 5

Wrong sensor type:

// Ensure sensor type matches your setup
ORB_SLAM3::System SLAM(vocab_file, config_file,
    ORB_SLAM3::System::STEREO,  // Change as needed
    true);

Image format issues:

// Ensure grayscale conversion
if (image.channels() == 3) {
    cv::cvtColor(image, image, cv::COLOR_BGR2GRAY);
}

Tracking Lost During Sequence

Symptoms: Tracking works initially but fails mid-sequenceCommon Causes:

Fast motion / motion blur
- Reduce camera frame rate
- Increase exposure time
- Add motion blur compensation
Textureless scenes:
- Lower FAST thresholds
- Ensure adequate lighting
- Add visual features to environment
Dynamic objects:
- Large moving objects can confuse tracking
- Try to maintain static background in view

Loop closure confusion:

Temporarily disable loop closing:

// In LocalMapping or LoopClosing
mbStopGBA = true;  // For debugging

Recovery:

ORB-SLAM3 has automatic relocalization
Ensure sufficient features from previous map
Consider resetting if unrecoverable

Scale Drift (Monocular)

Symptoms: Map scale changes over time in monocular modeExplanation:

Monocular SLAM has inherent scale ambiguity
Scale drift is expected without IMU or stereo

Solutions:

Use stereo or visual-inertial:
- Provides metric scale
- Eliminates scale drift
Add known-scale constraints:
- Implement custom scale constraints
- Use fiducial markers
Loop closure helps:
- Scale correction on loop detection
- Maintain visual overlap in trajectory

IMU Integration Issues

IMU Initialization Fails

Symptoms: “IMU not initialized” or worse tracking than visual-onlySolutions:

Verify IMU transformation:

# T_b_c1: Transform from camera to IMU
# Must be accurately calibrated
IMU.T_b_c1: !!opencv-matrix
  rows: 4
  cols: 4
  dt: f
  data: [r11, r12, r13, tx,
         r21, r22, r23, ty,
         r31, r32, r33, tz,
         0.0, 0.0, 0.0, 1.0]

Check IMU noise parameters:

Use manufacturer specifications

Or measure from static recording:

import numpy as np
gyro_noise = np.std(gyro_static)  # rad/s/√Hz
acc_noise = np.std(acc_static)    # m/s²/√Hz

Verify IMU frequency:

IMU.Frequency: 200.0  # Must match actual IMU rate

Ensure sufficient motion:
- IMU initialization requires motion
- Need acceleration and rotation
- Takes 2-3 seconds of dynamic motion

Time Synchronization Issues

Symptoms: IMU integration degrades performanceSolutions:

Hardware synchronization:
- Use hardware-synchronized camera-IMU
- RealSense D435i, T265 have built-in sync
Software synchronization:
- Interpolate IMU measurements
- Use timestamp association

Check timestamp units:

// Timestamps must be in SECONDS
double timestamp = timestamp_ns / 1e9;
SLAM.TrackStereo(imLeft, imRight, vImuMeas, timestamp);

Performance Issues

Cannot Achieve Real-Time Performance

Symptoms: Processing slower than camera frame rateSolutions:

Reduce feature count:

ORBextractor.nFeatures: 800  # From 1200
ORBextractor.nLevels: 6      # From 8

Disable viewer:

ORB_SLAM3::System SLAM(vocab_file, config_file,
    sensor_type, false);  // Disable viewer

Enable performance mode (Linux):

sudo cpupower frequency-set -g performance

Profile with REGISTER_TIMES:
```
// In include/Settings.h
#define REGISTER_TIMES
```
Rebuild and check ExecTimeMean.txt for bottlenecks.

Reduce image resolution:

cv::resize(image, image, cv::Size(640, 480));
// Update camera parameters accordingly

See Performance Tuning for detailed optimization.

High Memory Usage

Symptoms: RAM usage grows continuously or crashes with out-of-memorySolutions:

Reduce feature count:
```
ORBextractor.nFeatures: 800
```
Enable map point culling (default, but verify):
- Check LocalMapping thread is running
- Culling should happen automatically
Limit keyframe count:
- Modify LocalMapping parameters
- Implement periodic map saving/clearing

Monitor memory usage:

# While running ORB-SLAM3
watch -n 1 "ps aux | grep stereo_euroc"

Debugging Tips

Enable Verbose Output

// In your application, before creating System
#include "System.h"

// Set verbosity level
ORB_SLAM3::Verbose::SetTh(ORB_SLAM3::Verbose::VERBOSITY_VERY_VERBOSE);

// Levels:
// VERBOSITY_QUIET = 0
// VERBOSITY_NORMAL = 1
// VERBOSITY_VERBOSE = 2
// VERBOSITY_VERY_VERBOSE = 3
// VERBOSITY_DEBUG = 4

Use GDB for Segmentation Faults

# Compile with debug symbols
cd build
cmake .. -DCMAKE_BUILD_TYPE=Debug
make -j4

# Run with GDB
gdb --args ./Examples/Stereo/stereo_euroc \
    Vocabulary/ORBvoc.txt \
    Examples/Stereo/EuRoC.yaml \
    /path/to/dataset \
    timestamps.txt

# Inside GDB
(gdb) run
# When it crashes:
(gdb) backtrace
(gdb) frame 0
(gdb) print variable_name

Enable Time Profiling

Uncomment REGISTER_TIMES (Settings.h:24):
```
#define REGISTER_TIMES
```
Rebuild:
```
cd build && make -j4
```

Run and check output:

./Examples/Stereo/stereo_euroc ...
# After completion:
cat ExecTimeMean.txt

Visualize Trajectory

import numpy as np
import matplotlib.pyplot as plt

# Load trajectory
data = np.loadtxt('CameraTrajectory.txt')
timestamps = data[:, 0]
positions = data[:, 1:4]

# Plot top-down view
plt.figure(figsize=(10, 10))
plt.plot(positions[:, 0], positions[:, 1], 'b-', linewidth=2)
plt.scatter(positions[0, 0], positions[0, 1], c='g', s=100, label='Start')
plt.scatter(positions[-1, 0], positions[-1, 1], c='r', s=100, label='End')
plt.xlabel('X (m)')
plt.ylabel('Y (m)')
plt.legend()
plt.axis('equal')
plt.grid()
plt.savefig('trajectory.png')
plt.show()

Common Dataset-Specific Issues

EuRoC Dataset Issues

Problem: Cannot find images in datasetSolution:

# EuRoC structure:
# MH01/mav0/cam0/data/*.png
# MH01/mav0/cam1/data/*.png

# Verify structure:
ls /path/to/EuRoC/MH01/mav0/cam0/data/ | head

# Check timestamps file:
cat Examples/Stereo/EuRoC_TimeStamps/MH01.txt | head

Problem: Tracking fails immediatelySolution:

Use provided EuRoC.yaml (tested configuration)
Verify image equalization is disabled (default)
Check stereo rectification parameters

TUM-VI Dataset Issues

Problem: Slow bag file playbackSolution (from README.md:226-229):

# Rebag with smaller chunk size
rosrun rosbag fastrebag.py \
    dataset-room1_512_16.bag \
    dataset-room1_512_16_small_chunks.bag

Problem: Fisheye image distortionSolution:

TUM-VI uses fisheye cameras
Use Camera.type: "KannalaBrandt8"
ORB-SLAM3 works with original distorted images

RealSense Camera Issues

Problem: RealSense examples not compiledSolution:

# Install RealSense SDK
sudo apt-key adv --keyserver keyserver.ubuntu.com \
    --recv-key F6E65AC044F831AC80A06380C8B3A55A6F3EFCDE

sudo add-apt-repository \
    "deb https://librealsense.intel.com/Debian/apt-repo \
    $(lsb_release -sc) main"

sudo apt update
sudo apt install librealsense2-dev

# Rebuild ORB-SLAM3
cd build
cmake ..
make -j4

Problem: D435i camera not detectedSolution:

# Test camera
realsense-viewer

# Check USB connection (needs USB 3.0)
lsusb | grep Intel

# Ensure user has permissions
sudo usermod -aG video $USER
# Log out and back in

Getting Help

Before opening an issue, verify your problem is not covered in this troubleshooting guide.

Information to Provide

When seeking help, include:

System information:

uname -a
g++ --version
cmake --version
pkg-config --modversion opencv4

Build output:
- Full CMake configuration output
- Compilation errors (if any)
Runtime information:
- Command used to run ORB-SLAM3
- YAML configuration file
- Console output (verbose mode)
Dataset details:
- Dataset name and sequence
- Any preprocessing applied
- Timestamp format

Useful Resources

ORB-SLAM3 GitHub Issues
ORB-SLAM3 Paper (technical details)
README.md in repository root
Calibration_Tutorial.pdf for camera setup
ROS Answers for ROS-related issues

Quick Fixes Checklist

Before deep debugging, try:

Clean build: rm -rf build && mkdir build && cd build && cmake .. && make -j4
Verify vocabulary file extracted: ls -lh Vocabulary/ORBvoc.txt
Check dataset path is correct: ls /path/to/dataset
Use absolute paths for all file arguments
Test with provided example dataset (EuRoC MH01)
Disable viewer: set bUseViewer = false
Reduce feature count: ORBextractor.nFeatures: 800
Check RAM availability: free -h (need 2GB+ free)
Verify timestamp file format matches dataset

Most issues are caused by incorrect paths, missing dependencies, or configuration mismatches. Double-check basics first.

Get Started

Core Concepts

Guides

Examples

Advanced

Build Errors

Dependencies Not Found

Third-Party Library Build Failures

Linking Errors

Runtime Errors

Initialization Failures

Tracking Lost Scenarios

IMU Integration Issues

Performance Issues

Debugging Tips

Enable Verbose Output

Use GDB for Segmentation Faults

Enable Time Profiling

Visualize Trajectory

Common Dataset-Specific Issues

Getting Help

Information to Provide

Useful Resources

Quick Fixes Checklist

Build docs developers (and LLMs) love

Get Started

Core Concepts

Guides

Examples

Advanced

​Build Errors

​Dependencies Not Found

​Third-Party Library Build Failures

​Linking Errors

​Python-Related Build Errors

​Runtime Errors

​Initialization Failures

​Tracking Lost Scenarios

​IMU Integration Issues

​Performance Issues

​Debugging Tips

​Enable Verbose Output

​Use GDB for Segmentation Faults

​Enable Time Profiling

​Visualize Trajectory

​Common Dataset-Specific Issues

​Getting Help

​Information to Provide

​Useful Resources

​Quick Fixes Checklist

Build docs developers (and LLMs) love

Build Errors

Dependencies Not Found

Third-Party Library Build Failures

Linking Errors

Python-Related Build Errors

Runtime Errors

Initialization Failures

Tracking Lost Scenarios

IMU Integration Issues

Performance Issues

Debugging Tips

Enable Verbose Output

Use GDB for Segmentation Faults

Enable Time Profiling

Visualize Trajectory

Common Dataset-Specific Issues

Getting Help

Information to Provide

Useful Resources

Quick Fixes Checklist