Before you begin

If you don't know what the problem is yet or how to fix it, try running roswtf first, which is like a FAQ implemented in code. It will look at your configuration and what is running and try and diagnose problems. You can either run it by itself, or you can give it the name of a roslaunch file, e.g.



roswtf myfile.launch

If you're having problems with things that are running, try running roswtf while they are still up.

Common Problems

Master Not Running

If you get this message:

Unable to register with master node [http://localhost:11311/]: master may not be running yet. Will keep trying.

You need to launch roscore:


Network Configuration

If you're having trouble communicating between processes.

  • /!\ Cannot connect/connection refused or "Failed to contact publisher"

    • (./) Make sure that all hosts in the network can ping each other by name. If not set ROS_IP or ROS_HOSTNAME or fix your hostnames so that the computers are reachable by name.

  • /!\ md5sum mismatch

    • This is either two different versions of a message at either end or actually different messages.
    • (./) Make sure that all directories are up to date and have been rebuilt by doing a rosmake in any package you are launching

      • Note: If you are running on multiple machines they must all be consistent.
    • (./) Make sure that the sender and receiver are expecting the same message

    • (./) If you're playing out of a log file the contents may be out of date see rosrecord

  • /!\ WARNING: IP address for local hostname 'mylaptop' does not appear to match any local IP address ( Your ROS nodes may fail to communicate.

    • This usually occurs when your hostname, e.g. 'mylaptop', isn't configured with DNS, which is common with laptops and other situations. As ROS is capable of running across multiple computers, it is important to configure it to use the correct IP address.
    • (./) Please set the ROS_IP environment variable to set the correct IP address to use.

  • /!\ WARNING: ROS_IP may be incorrect: ROS_IP [aaa.bbb.ccc.ddd] does not appear to be a local address

    • This warning may be given after running roswtf, it indicates that the ROS_IP environment variable is not correctly set to the IP of the workstation.

    • (./) Re-configure your ROS_IP environment variables

Failed Launching

  • /!\ A node is not launching from a launch file

    • (./) Make sure the executable exists

    • (./) Check the network connectivity (above)

  • /!\ Problems with pr2_etherCAT see pr2_etherCAT/Troubleshooting

Failure to Compile

  • /!\ A package doesn't compile

    • (./) Confirm all necessary sysdeps are installed (on ubuntu bash <(rosdep satify PACKAGE_NAME) )

    • (./) Do a rosmake to make sure all dependencies are built ahead of time

    • (./) check that all packages are at the same version/revision

    • (./) check that there are no local changes related to the problem using 'svn st' and 'svn diff'

    • (./) If a specific package is giving trouble or the error is related to a package try 'make clean' in the package and/or related packages to make sure it's not old state

    • (./) "Undefined reference" errors are linker errors. Check that you are linking your libraries in your CMake. See: Catkin/CMake

    • (./) Confirm that you have installed all the ros packages. Read through the compiler output and check if packages aren't found. Either add them to your package.xml or sudo apt-get install ros-distro-packagename.

    • (./) Make sure your compiler uses the correct C++-Version. ROS Melodic requires C++14.

      • If your cmake version is 3.1 or above, you can fix this by appending "-DCMAKE_CXX_STANDARD=14" to your initial "catkin_make" call. If your cmake version is older you can use "-DCMAKE_CXX_FLAGS='-std=c++14'" or set the environment variable "CXXFLAGS=-std=c++14".
  • /!\ If the errors are related to boost or log4cxx:

    • (./) make sure that boost and log4cxx are in /opt/ros or ROS_BOOST_PATH is set, see ROS/Installation (check this using rosboost-cfg)

Transform Issues

See tf documentation

Recommended Checks

Things to do before asking for help

  • Confirm that all code is at the expected revisions without unexpected changes.
  • Confirm that everything being used has been built/rebuilt since any changes have happened to the system


        you@yourcpuname:~$ cd catkin_ws
        you@yourcpuname:~$ catkin_make

    • If you're wondering why code from source isn't accessible by your rosrun or are uncertain your node is being run:

        you@yourcpuname:~$ source devel/setup.bash

    • This will allow ROS to choose your developer code over the /opt/ros/distro/ code.

Information Needed for Remote Debugging

  • /!\ all the steps to reproduce the problem will make remote debugging much more successful. Including information like:

    • The versions of all repos running (svn revision numbers and urls. or release names with versions)
    • The OS you're running
    • What sysdeps you have installed
    • How you have setup your environment
    • What machines you are running and how they are connected
    • Confirmation you have run rosmake since updating on all packages at issue.
  • /!\ Gather all relevant error outputs such as:

    • The log file of the master ( if debugging connectivity issues)
    • The log file of the launch script (if debugging startup)
    • The launch file(s) or instructions for how to reproduce the problem
    • Log files of appropriate nodes which are crashing/functioning improperly
    • If crashing a gdb backtrace or core file

Wiki: ROS/Troubleshooting (last edited 2019-02-26 18:51:23 by ChristopherWecht)