.. include:: vars.rst

.. _section-troubleshooting:

Troubleshooting
***************

This section covers a few issues you may run into while deploying your system
with |CDS|.

.. note::

    All the issues addressed in this section assume that your applications
    would communicate directly with each other without |CDS|.


My applications don't communicate
=================================

There can be many reasons why your applications may not communicate with |CDS|. 
Nevertheless, below are some of the common issues you may run into.

Make sure your application can accept unknown peers
---------------------------------------------------

For |DPs| to discover each other through |CDS|, they require the ability to
accept unknown peers. This is a Discovery QoS setting whose default value is
true. Make sure your |DPs| are created with this value. For instance, you can
add the following XML setting to the ``<participant_qos>`` element used
by your application:

.. code-block:: xml

    <discovery>
        <accept_unknown_peers>true</accept_unknown_peers>
    </discovery>


Check that your initial peers list points to |CDS|
--------------------------------------------------

Your applications are required to provide discovery information to |CDS|. 
For that, they must know where |CDS| is running. You provide this 
information through the initial peers list using an 
:ref:`RTPS peer descriptor<section-domain-list-rtps-peer-descriptor>`.

You can specify the initial peers list through the Discovery QoS (
programmatically, XML, or the environment). For instance, assuming a |CDS| 
instance is running on UDP, port 7400 and host CDS_HOST:

.. code-block:: xml
   :caption: XML

    <discovery>
        <initial_peers>
            <element>rtps@udpv4://CDS_HOST:7400</element>
        </initial_peers>
    </discovery>

.. code-block:: bash
   :caption: environment

    export NDDS_DISCOVERY_PEERS=rtps@udpv4://CDS_HOST:7400


See where your |CDS| instance is listening
------------------------------------------
 
To verify that |CDS| is actually listening where you specified, you can run
with ``-verbosity 4`` and look for the following message:

.. code-block:: bash
    
    ...
    [CDS DETECTOR] listening for announcements on:
	udpv4://172.17.0.2:10000
    ...

The message above indicates that |CDS| is listening on the interface
``172.17.0.2`` over the ``UDP`` transport on port ``10000``.

Additionally, make sure the |CDS| location is reachable from where your
applications run.


|CDS| log errors
================

This section shows a few of the errors that |CDS| shows on startup.

Invalid port
------------

Error log output if an invalid port is specified.

.. code-block:: bash

    ...
    NDDS_Transport_UDPv4_Socket_bindWithIp:OS bind() failure, error 0: Success
    NDDS_Transport_UDPv4_Socket_bindWithIp:invalid port 70000
    NDDS_Transport_UDPv4_SocketFactory_create_receive_socket:invalid port 70000
    NDDS_Transport_UDP_create_recvresource_rrEA:!create socket
    COMMENDLocalReaderRW_init:!create unicast entryPort
    ...

The example above shows an error binding a UDP socket to port 70000, which is
out of the valid port range for this transport.

Port already in use
-------------------

Error log output if a port that is already in use is specified.

.. code-block:: bash

    ...
    NDDS_Transport_UDPv4_Socket_bindWithIp:0X1CE8 in use
    NDDS_Transport_UDPv4_SocketFactory_create_receive_socket:invalid port 7400
    NDDS_Transport_UDP_create_recvresource_rrEA:!create socket
    COMMENDLocalReaderRW_init:!create unicast entryPort
    ...

The example above shows an error binding a UDP socket to port 7400, which is
being used by other process.