# colcon test: Return code 2. Some tests failed. See output for details.

- **ID:** `ros2/colcon-test-return-code-2`
- **Domain:** ros2
- **Category:** test_error
- **Error Code:** `2`
- **Verification:** ai_generated
- **Fix Rate:** 85%

## Root Cause

One or more test cases in the ROS2 package returned non-zero exit status, often due to assertion failures, missing dependencies, or runtime exceptions during test execution.

## Version Compatibility

| Version | Status | Introduced | Deprecated |
|---------|--------|------------|------------|
| Humble | active | — | — |
| Iron | active | — | — |
| Jazzy | active | — | — |
| Rolling | active | — | — |

## Workarounds

1. **Run colcon test with --event-handlers console_direct+ to see detailed test output and identify failing tests.** (90% success)
   ```
   Run colcon test with --event-handlers console_direct+ to see detailed test output and identify failing tests.
   ```
2. **Check test log files in 'log/test_*' directory for specific failure messages.** (85% success)
   ```
   Check test log files in 'log/test_*' directory for specific failure messages.
   ```
3. **Update test dependencies in package.xml and run 'rosdep install -i --from-paths src' to ensure all test packages are installed.** (75% success)
   ```
   Update test dependencies in package.xml and run 'rosdep install -i --from-paths src' to ensure all test packages are installed.
   ```

## Dead Ends

- **Re-running colcon test without cleaning build artifacts** — Stale test binaries or cached results may mask underlying failures; a clean rebuild is needed. (40% fail)
- **Disabling all tests with --packages-select and --mixin skip-tests** — This bypasses the problem without fixing it, leaving broken tests for later. (80% fail)
- **Upgrading colcon-core to latest version** — The error is test-logic related, not a colcon tool bug. (30% fail)