Start Troubleshooting From a Clean Shell, Not From Yesterday's Environment

A long-lived development terminal can accumulate hidden state. You may have sourced multiple workspaces, changed directories, exported environment variables, and launched several processes before the current failure appears.

When package lookup becomes confusing, a clean shell is often evidence, not inconvenience.

Rebuild the intended environment deliberately

Open a new terminal.

Source only the Jazzy underlay:

source /opt/ros/jazzy/setup.bash

Verify:

echo $ROS_DISTRO

Expected:

jazzy

Then source the intended overlay:

source ~/robot_ws/install/setup.bash

Now verify the bringup package:

ros2 pkg prefix robotnix_bringup

Expected prefix should belong to:

~/robot_ws/install/robotnix_bringup

The exact absolute path depends on the user account.

Why package prefix is stronger than memory

A student may say:

I know I sourced robot_ws earlier.

That is not current evidence.

This command:

ros2 pkg prefix robotnix_bringup

shows which installed package prefix the current shell resolves.

If it points to:

/home/student/old_ws/install/robotnix_bringup

then the shell is not using the package you think it is.

That observation changes the diagnosis immediately.

Do not pile overlays on top of one another while guessing

Imagine this shell history:

source /opt/ros/jazzy/setup.bash
source ~/old_ws/install/setup.bash
source ~/robot_ws/install/setup.bash
source ~/experiment_ws/install/setup.bash

Now package lookup behaves unexpectedly.

You can spend twenty minutes trying to reconstruct precedence from shell history.

A cleaner experiment is:

new terminal
source Jazzy
source only robot_ws
verify prefix

If the clean shell behaves correctly, the earlier problem was environment contamination rather than package source.

Check the underlay too

The overlay depends on the intended underlay.

If:

echo $ROS_DISTRO

reports:

humble

while the workspace was developed for Jazzy, stop and resolve the distribution mismatch before trusting build/runtime evidence.

A package name resolving successfully does not prove the entire environment is the intended distribution.

Build state and shell state remain separate

A fresh shell can fail to find robotnix_bringup even though yesterday's build succeeded.

Check whether the install setup file exists:

ls ~/robot_ws/install/setup.bash

If it exists, source it before deciding a rebuild is necessary.

If it does not exist, the workspace may not have been built successfully yet, or the path may be wrong.

The evidence tells you which branch to follow.

A clean shell can expose stale documentation

Suppose the startup guide says:

source ~/ros_ws/install/setup.bash

but the actual course workspace is:

~/robot_ws

Students who have the correct workspace open in one terminal may not notice the bad documentation because their environment is already sourced.

A clean-shell runbook test exposes the broken path immediately.

That is why operational documentation should be tested from a known starting state.

Record shell assumptions explicitly

A reproducible runbook should state:

OS: Ubuntu 24.04
ROS distribution: Jazzy
underlay setup: /opt/ros/jazzy/setup.bash
overlay setup: ~/robot_ws/install/setup.bash
expected package prefix: ~/robot_ws/install/robotnix_bringup

Do not rely on:

open the usual terminal

or:

run the same setup as before

Those instructions only work for the person who remembers the hidden context.

Worked failure: package resolves from an old workspace

Observed:

ros2 pkg prefix robotnix_bringup

returns:

/home/student/old_ws/install/robotnix_bringup

Source file being edited:

/home/student/robot_ws/src/robotnix_bringup/launch/demo_pair.launch.py

The runtime keeps ignoring your edits.

The first repair is not another rebuild.

Open a clean shell and source:

source /opt/ros/jazzy/setup.bash
source ~/robot_ws/install/setup.bash

Then confirm the prefix again.

Only after the shell resolves the intended workspace does it make sense to compare source and installed resource freshness.

Your turn

For each result, state the most likely next check.

A

echo $ROS_DISTRO

prints nothing.

B

It prints jazzy, but ros2 pkg prefix robotnix_bringup says package not found.

C

The package prefix resolves to old_ws.

D

The package prefix resolves to robot_ws, but the launch default still looks stale.

Then write a clean-shell startup preamble that another student could copy exactly before running the Week 15 launch.

In the next lesson, you will diagnose failures that occur after the shell and package prefix are already correct.