.. 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_Heading|
----------------------------------------------------------

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 Variables

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


See Where Your |CDS_Heading| 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_Heading| Log Errors
========================

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

Invalid Port
------------

If an invalid port is specified, you may see this error log output:

.. 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 messages above indicate an error binding a UDP socket to port 70000, which is
out of the valid port range for this transport.

Port Already in Use
-------------------

If a port that is already in use is specified, you may see this error log output:

.. 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 messages above indicate an error binding a UDP socket to port 7400, which is
being used by other process.