Diagnostics | LiveKit Documentation

Overview

The LiveKit Portal for ROS publishes standard ROS diagnostics on topic /diagnostics. Use them to confirm that a node initialized, is connected to its LiveKit room, and can forward topics, services, video, and remote ROS CLI calls. Diagnostics publish periodically and they help you identify connection instability or growing failure counts, as well as other issues, while a robot is in the field. See the diagnostics ROS wiki for more information.

Inspect the latest diagnostic array with:

ros2 topic echo /diagnostics --once

Each status is named ros_portal: <task> and uses the standard ROS diagnostic levels: OK, WARN, and ERROR.

Troubleshooting fields

Start with these statuses and fields when troubleshooting:

Status	Check	Indicates
`ros_portal_status`	`initialized`, `components_inactive`	Whether LiveKit Portal for ROS started successfully and all expected components are active.
`ros_portal_status`	`config_path`, `local_identity`	Which configuration the node loaded and its LiveKit participant identity.
`connection_health`	`state`, `room_name`, `num_peers`	Whether the node is connected to the expected room and can see remote participants.
`connection_health`	`reconnect_count`, `connection_loss_count`	Whether an otherwise connected node has experienced unstable connectivity.
`connection_health`	`rtc.transport.current_round_trip_time_ms`, `rtc.traffic.packets_lost`, `rtc.traffic.max_jitter_ms`	Network quality signals that can help explain delayed or unreliable realtime traffic.
`topic_forwarder`	`inbound_schemas_incorrect`	Whether received topic data uses an unexpected ROS message schema.
`cli_manager`	`topic_pub_cache_full_rejections`, `service_call_cache_full_rejections`	Whether remote publish or service-call requests are being rejected because a cache is full.
`cli_manager`	`remote_participant_not_found`, `remote_transport_failures`, `remote_malformed_responses`	Why remote ROS CLI requests fail.

The build_info status reports the LiveKit Portal for ROS, LiveKit SDK, and ROS distribution versions. Include it when collecting diagnostic output for support or when comparing environments.

Aggregate diagnostics

The LiveKit Portal for ROS publishes raw diagnostics. To group them under a single LiveKit Portal for ROS tree on /diagnostics_agg, run the standard diagnostic_aggregator node alongside it.

For example, save this configuration as ros_portal_diagnostics_aggregator.yaml:

/**:
  ros__parameters:
    path: ROS Portal
    connection_health:
      type: diagnostic_aggregator/GenericAnalyzer
      path: Connection Health
      contains: ['connection_health']
    ros_portal_status:
      type: diagnostic_aggregator/GenericAnalyzer
      path: Node Status
      contains: ['ros_portal_status']

Then start the aggregator and inspect its output:

ros2 run diagnostic_aggregator aggregator_node \
  --ros-args --params-file ros_portal_diagnostics_aggregator.yaml

ros2 topic echo /diagnostics_agg --once

Add analyzers for topic_forwarder, cli_manager, or build_info when those statuses are relevant to your deployment.

Additional resources

The following resources provide more information about diagnostics.

LiveKit Portal for ROS diagnostics reference

The complete diagnostic task and field reference, including status-level behavior and aggregation configuration.

ROS Diagnostics