Diagnose Workspace and Build Failures

Most beginner workspace failures fit a small number of boundaries.

Wrong directory

Symptom: colcon build runs somewhere that is not the workspace you intended.

Inspect:

pwd
ls

Package placed outside src

Inspect:

find ~/ros2_ws -maxdepth 3 -name package.xml -print

Compare to the intended tree.

Missing dependencies

Re-run the documented dependency check from the workspace root:

rosdep install -i --from-path src --rosdistro jazzy -y

Build failure

Read the colcon summary and inspect relevant files under log/. Do not continue to sourcing as if the package built successfully.

Built but ros2 run cannot find your executable

This is a classic later failure. Check:

1. did the package build?
2. are executable entry points/configuration correct?
3. did this terminal source the overlay?

Stale shell

Open a clean terminal and source in known order:

source /opt/ros/jazzy/setup.bash
source ~/ros2_ws/install/local_setup.bash

Unit gate

From a clean state, prove:

underlay sourced
→ workspace source exists
→ dependencies resolved
→ colcon build succeeds
→ install space exists
→ overlay sourced
→ local package/executable is discoverable

That sequence is the bridge to writing your own package next.