# RViz2 failures

Check these in order before rebuilding or restarting the stack.

- **Nothing renders**
  - Confirm Global Options → Fixed Frame names a live frame.
  - Prove a current transform exists from that frame to the message frame.
  - An empty display and a red transform warning are often the same TF failure.

- **The topic publishes but its display stays empty**
  - Compare the publisher's actual type and QoS with the display.
  - Best-effort sensors and transient-local maps are common cases where a
    display's default policy is incompatible.
  - Inspect the `ros2` skill only if this is a graph/QoS issue rather than an
    RViz setting.

- **Data appears frozen or repeatedly expires in simulation**
  - Confirm `/clock` advances and RViz plus every producer agree on
    `use_sim_time`.
  - Check timestamps and TF freshness, not only topic frequency.

- **A saved config loses one display**
  - Look for a missing plugin or package on the new machine. RViz can load the
    remainder of the config while one display is greyed out or errored.
  - Re-check topic namespaces and frame names when moving between robots.

- **RViz is needed on a remote or headless host**
  - RViz2 is a Qt/OpenGL desktop application, not a web server. Use `foxglove`
    for the normal remote path instead of making X forwarding a project
    dependency.
  - Because ROS 2 has no normal native macOS workflow, running RViz2 on a Mac
    also inherits the container/display constraints from `environments`.

For Nav2, a useful evidence set contains TF and RobotModel plus map, global and
local costmaps, plan, footprint, and the raw sensor feeding the costmaps. Once
those inputs render correctly, route incorrect navigation behavior to
`navigation`.

---
name: rviz2
description: Inspect and debug live ROS 2 robot state with RViz2.
---

# RViz2

Treat RViz2 as a consumer of ROS evidence. A blank display usually means its
frame, message, QoS, or time contract is wrong.

## Build a focused view

- Start with a fixed frame that exists now, then add only the displays needed
  for the question being asked.
- Prefer adding by topic when discovering a graph; it helps match message type
  to display type.
- Keep a saved `.rviz` configuration per robot and task. Do not rebuild the
  display list on every run or make one unreadable everything-dashboard.
- For navigation, view raw sensors and TF alongside map, costmaps, footprint,
  plan, and robot model so upstream data can be distinguished from Nav2 output.

## Read what the display is telling you

- A red or empty display is evidence about the input boundary, not proof that
  RViz itself is broken.
- Check fixed frame and TF first, then publisher/display QoS, then simulation
  time and `/clock`.
- Compare the configured topic and namespace with the live graph; stale configs
  often point at an old robot name.
- A missing display plugin can fail one saved display while the rest of the
  config continues to load.

Read [failures](FAILURES.md) when something does not render. Cross into `ros2`
only when the evidence points to TF, QoS, graph, or time at the publisher. Cross
into `navigation` when those inputs are healthy but a costmap, plan, or
controller result is wrong.

Use `foxglove` instead for a headless, remote, browser, or shareable workflow;
use `rerun` for data-centric ML and non-ROS logging. If the viewer has not been
chosen, use `visualization` first.

## Done

- The fixed frame is present and every displayed message transforms into it.
- Display QoS and topic namespaces match their publishers.
- Simulation time is consistent when applicable.
- The saved config opens into a focused, useful debugging view.
- Any CLI or UI details were checked against the installed RViz2 build and
  current [RViz documentation](https://github.com/ros2/rviz).