Troubleshooting & FAQ

Contents

• Installations issues
• Runtime issues
• FAQ

Can't find your issue here? Open an issue and we'll get back to you asap.

Installation issues

A wall of Unable to create glx fbconfig

Gazebo needs the host's GPU driver for the window and for every rendering sensor (camera, depth camera, gpu_lidar) which it implements by rendering the scene from the sensor's viewpoint. gz sim -s drops the window, not the renderer, so a headless run that spawns a sensor-carrying vessel needs the driver just as much as --gui does. The failure appears the moment such a model spawns, not at startup, because the renderer is built lazily.

A nix-built binary cannot reach that driver on a non-NixOS host. Install nixGL once into your own profile and both mise run sim and the packaged lotusim find it by themselves:

nix profile add github:nix-community/nixGL#nixGLIntel

nixGLIntel covers Intel and AMD, and is also the right choice on a hybrid Intel/NVIDIA laptop. NVIDIA-only machines need nixGLNvidia, which has to match the host's driver version and so installs with --impure, which is also why nixGL cannot be a dependency of this repository: it must match the machine, not the project. Set LOTUSIM_GL_WRAPPER to a name or path to override the choice. On NixOS none of this applies.

scripts/gl-wrapper.sh is the single lookup, shared by the mise task and the lotusim wrapper the flake builds. The README gives users the one-line form of this.

The GUI aborts inside Ogre2's EGL setup

The renderer has fallen back from GLX and chosen a GPU by enumeration order, which on a hybrid machine can be the NVIDIA device that nix's Mesa cannot drive against the proprietary nvidia-drm module. Run mise run sim --gui --debug to see the fallback — -v1 and above report it. LIBGL_ALWAYS_SOFTWARE=1 renders on the CPU and always works; masking the unwanted /dev/dri nodes with bwrap forces the other GPU.

gz sim --iterations N never exits

A world with a camera or gpu_lidar runs its iterations, writes its log, and then hangs: the rendering thread never joins. Bound such runs with timeout -s KILL and read the log. The exit status carries nothing anyway, since gz exits 0 on a model it failed to load.

Runtime issues

Unity scene appears black

Check that your graphics drivers are properly installed and up to date. HDRP (used for the water rendering system) requires a working GPU driver.

Simulation runs but no vehicle appears in the Web UI

• Make sure you selected a scenario file (e.g. demo.yaml) under Launch Scenario and clicked Launch Scenario. Only the map will show until a scenario is loaded.
• Check the terminal running lotusim run for errors.
• Clear the scenario and refresh the page, then try again.

Vessel is not working with the dynamism engine Xdyn

When building your own examples, keep the following in mind:

Vessel naming convention

When entities are spawned, their names are automatically assigned in the format model_name_0, model_name_1, ... The index increments for each new instance. 👉 Make sure you use the correct vessel name when sending commands, otherwise they will not be applied.

Underwater vs surface behavior (important for XDyn connections)

XDyn determines whether a vessel is underwater or surface based on its z position: z <= -10 → underwater z >= 10 → aerial otherwise → surface

Each domain (underwater, surface, aerial) uses a different WebSocket connection (URI). In these examples, vessels are spawned underwater, so only the underwater XDyn connection is used.

⚠️ If your vessel transitions between domains (e.g., from surface at z = 0 to underwater at z = -100), or if you spawn vessels in different domains, you must:

• run XDyn instances for each relevant domain, and
• ensure each one is listening on the correct URI/port.

---

General questions

What are the advantages of moving from only Gazebo to LOTUSim?

LOTUSim is a simulation integration project designed to allow users to quickly start maritime simulations. While built using a Gazebo backbone, LOTUSim doesn't rely solely on it. It's fundamentally different in purpose and design.

It extends Gazebo with:

1. Multi-agent System
   Built-in MAS makes interaction management between models/agents easier.

2. External Physics System
   Connect to external physics engines and distribute processing across machines.

3. External Rendering
   Gazebo GUI is limited. LOTUSim enables better rendering via Unity or other engines.

4. Additional Sensors
   Marine-specific custom sensors are in development.

Should I Use Unity?

That’s up to you. The simulation interface is open—you can integrate your own rendering system.

Recommendation: Use the provided renderer for the best experience.