Troubleshoot a scene with preview

A failed preview tells you what happened and which task method to inspect. Use it to fix the scene before you spend time training. For the checks, exit codes, and recording, read Preview. For the usual preview workflow, read Preview before training.

Read the failure before changing code

Preview first streams a job log with [stage] blocks, such as [settle] and [training-loop]. The report printed after the log has the same rows under headings such as Settle Failed. Its warning and failure rows include Problem:, Fix:, Owner:, and sometimes Detail:.

Start with the first ✗ row and its report heading. Read its Problem: and Owner: lines, then its Fix: line when it has one. If that row has no fix, scan the other failures in the stage for more specific advice. Those lines name the part of your task to inspect, for example build(), get_dones(), or reset_idx(). Make the change in your own task code or robot asset, then run the full preview again. The fix is confirmed when the command exits 0.

Later failures can be effects of the same mistake. A robot below the floor can also move too fast and miss a joint target. Fix the starting pose first, then rerun preview instead of treating every later row as a separate defect. The reset example below shows the reverse case: an early short-episode row is an effect, while the later reset row identifies the cause. Read the advice on each failure before deciding where to edit.

The excerpts below are real output from the troubleshooting beds, cut down to the key lines. Detail: lines, recording times and repeated rows are left out.

Robot starts under the floor

This is a Settle failure. The speed row appears first, but the floor row later in the same stage identifies the planted cause. Read both rows before editing.

  Settle          Failed
    ✗ slider_to_cart stays within a sane speed
      ...
    ✗ Robot stays above the floor
      Problem: The robot's base was more than 0.25 m below the floor.
      Fix: Preview cannot tell which caused this: raise the spawn pose (initial_pose in build() or the pose reset_idx() sets) or repair the robot's collision mesh.
      Owner: Your task or your robot
      Detail: lowest base height -0.50 m above the floor

The speed and joint-tracking failures are knock-ons from the bad starting pose. Look in build() for the robot’s initial_pose. In this task, restore the normal pose:

self.robot = simulo.Robot(asset=cartpole, initial_pose=simulo.Pose.from_xyz(0.0, 0.0, -0.5))
self.robot = simulo.Robot(asset=cartpole, initial_pose=simulo.Pose.identity())

Run simulo run preview.py again. The fixed bed reports:

  Settle          Passed
    ✓ Driven joints and base came to rest

Episodes end at once

This is a Training loop failure. The advice points to the task method that decides whether an episode has ended. A condition that is true at reset ends every episode before the task can run.

  Training loop   Failed
    ✗ Episodes last long enough
      Problem: The task ends episodes after five steps or fewer on average.
      Fix: Check get_dones() for a condition already true at the reset state, and episode_length_s.
      Owner: Your task

Look in get_dones(). The bed compared the cart position with a value that was already exceeded. Compare it with your task’s own track-limit attribute instead:

cart_out = torch.abs(joint_pos[:, cart_idx]) > -0.1
cart_out = torch.abs(joint_pos[:, cart_idx]) > self.max_cart_pos

Run simulo run preview.py again. The fixed bed reports:

  Training loop   Passed
    ✓ Episodes last long enough
    ✓ Reset restores the requested state

Reset does not restore the requested state

This bed first reports short episodes in the Training loop. Read on: the reset row shows that the task calculated a starting state but did not apply it. The short episodes are a knock-on from that stale state.

  Training loop   Failed
    ✗ Episodes last long enough
      Problem: The task ends episodes after five steps or fewer on average.
      Fix: Check get_dones() for a condition already true at the reset state, and episode_length_s.
      Owner: Your task
    ...
    ✗ Reset restores the requested state
      Problem: A reset left a non-finite or mismatched starting state.
      Fix: Make reset_idx() restore joint positions and velocities and the base pose and velocity.
      Owner: Your task

Look in reset_idx(). Reset the robot:

self.robot.reset(env_ids)

Then apply the positions and velocities the method calculated:

self.robot.set_joint_state(joint_pos, velocities=joint_vel, env_ids=env_ids)

Run simulo run preview.py again. The fixed bed reports:

  Training loop   Passed
    ✓ Episodes last long enough
    ✓ Reset restores the requested state

Robot starts inside a box

This is a Joint sweep failure. The first failing row says the joint did not move. Its advice cannot distinguish an obstruction from a drive problem, so inspect the scene first. In this bed, speed failures later in Random moves are effects of the same overlap.

  Joint sweep     Failed
    ✗ slider_to_cart responds to its velocity target
      Problem: slider_to_cart was not moving at the end of the command.
      Fix: Preview cannot tell which caused this: something holding slider_to_cart in place, such as the robot starting inside another object, or slider_to_cart's drive. Check the spawn pose (initial_pose in build() or the pose reset_idx() sets) and props in build() first, then slider_to_cart's damping and effort limit in the robot's drive.
      Owner: Your task or your robot

Look in build() for props placed at the robot’s starting position. In this task, move the box down to the floor (or off the robot):

pose=simulo.Pose.from_xyz(0.0, 0.0, 2.0),
pose=simulo.Pose.from_xyz(0.0, 0.0, 0.3),

Run simulo run preview.py again. The fixed bed reports:

  Joint sweep     Passed
    ✓ slider_to_cart responds to its velocity target
  Random moves    Passed
    ✓ Stable under random actions

Symptom to code location

Report row or advice	Likely cause	Where to look
Robot stays above the floor	The robot starts below the floor, or its collision mesh needs repair.	build() initial_pose, then a pose set by reset_idx() or the robot collision mesh.
Episodes last long enough and advice to check get_dones()	An end condition is already true at reset.	get_dones() and episode_length_s.
Reset restores the requested state	The task calculates reset state without applying all of it.	reset_idx().
A joint was not moving and advice mentions something holding it in place	A spawn pose or scene prop may overlap the robot, or the drive may need repair.	build() spawn pose and props first, then the joint drive.
A joint exceeded the explosion speed after an earlier failure	The speed row may be an effect of the earlier scene or reset problem.	Fix and rerun the earlier failure before changing the joint.