Troubleshooting

Start with the robot’s terminal (where you ran ros2 launch): it shows connection problems, task starts and results, and sync errors. The messages below are copied from real runs.

The robot doesn’t show up

The log shows Handshake status 403 Access denied

The project ID or secret key is wrong, or the key is switched off, frozen or deleted. Copy both again from the project’s Dashboard page (Secret Key Manager); generate a new key if you don’t have the old one.

The log shows Handshake status 500 or the connection keeps retrying

Check the project ID is complete (a UUID such as 8fd1d8a3-4b35-4158-bff4-4c7757a95a4d) and that the robot can reach https://xparo.in (try curl -I https://xparo.in on the robot). The robot retries every 5 seconds on its own.

The node stops at start-up with InvalidParameterTypeException: Trying to set parameter 'xparo_ads_display' to 'False' of type 'BOOL'

off (and on, yes, no) must be quoted: "xparo_ads_display:='off'". See Configuration.

You use ~/xparo_config.json and ros2 launch

The launch file’s defaults override the file. Pass the values as launch arguments, or use ros2 run xparo xparo_ros (see Configuration).

“Package ‘xparo’ not found”

Source the workspace in every new terminal: source ~/xparo_ws/install/setup.bash. Check the build with ros2 pkg executables xparo.

It was online, now it’s offline

The dashboard shows a robot online while its heartbeat (every 30 seconds) arrives; after 90 seconds without one it shows offline. Check that xparo_ros is still running and the robot has internet. Heartbeats travel over HTTPS, so a network that allows WebSockets but blocks HTTPS (or the reverse) is not enough. After a short outage the robot reconnects by itself; results of tasks that finished meanwhile are sent when it is back.

Tasks

stage_mismatch: This robot is configured for xparo_stage=’production’ and cannot run a ‘development’-stage task.

New tasks are in the development stage and robots default to production. Start the robot with xparo_stage:=development, or raise the task’s stage on the Tasks page.

No robot resolved to run this task – check Fleet Task Distribution and robot connectivity.

With Single robot, tick a robot under Target Robot in the task’s Fleet Task Distribution tab.

<robot> is offline (last seen …), so the task wasn’t sent to it.

Start xparo_ros on the robot.

invalid_tree: <Something> isn’t a node this robot knows

A typo in the tag, or a custom node that did not load on the robot. See Custom nodes (“When a node isn’t found”).

unknown_task after /xparo/run_task

The robot has not received that task yet. Let it reconnect (restart xparo_ros) after creating or editing the task while it was offline.

Failed to parse /xparo/run_task message: Expecting property name enclosed in double quotes

The JSON lost its quotes in the shell. Escape the inner quotes exactly as in Run a task from the robot.

timeout

The run passed the task’s time limit. Raise it on the Tasks page, or look at failed_node for the node that never finished.

A tree input is empty

Check the task’s Task Behaviour tab: every {name} needs a source. For runs started on the robot, inputs mapped From env are currently empty (a known issue); use a default or a task param instead.

The tree runs but the robot doesn’t move

The XPARO nodes NavigateTo, DockRobot, SpeakText, PlayAudio, NotifyPatient, LoadNextDelivery and CheckBatteryLevel are placeholders that move no hardware. Use your own custom nodes.

Remote tools

Terminal command does nothing or times out

Each command runs on its own and stops after 30 seconds; interactive programs (editors, prompts) cannot run. Chain commands with &&.

Teleop doesn’t move the robot

Teleop publishes /joy. Check with ros2 topic echo /joy on the robot, and make sure a node turns /joy into motion.

Reboot, Wi-Fi or Bluetooth asks for a password

The robot needs the sudo password of the user xparo_ros runs as. To avoid the prompt, allow that user passwordless sudo for reboot (and nmcli / bluetoothctl) on the robot.

Recording doesn’t start

With record_bags:=true the start mode decides: a fresh robot waits for a start command. Press Start in the Rosbag panel, or set Auto Start in Database → Sensors and save while the robot is online. See ROS bag recording.

AI assistant

No valid API keys available. Please add or check key statuses.

Add an LLM key on the project’s Dashboard page (LLM API Key Manager), or switch an existing one back on.

Messages that are normal

[WARN] nav2_msgs not available. Subscriber will not start.

Nav2 isn’t installed; only its live view is affected.

No rosbag2 recorder is running -- recording controls stay idle until one starts

Recording is off.

[bt_engine plugin_loader] failed to load '.../custom_node_files/python/greet_example.py'

Missing example files in the current package version; harmless. The dashboard may also show a red “battery_ok_example_cpp (cpp) failed to sync: source file missing on disk” message for the same reason.