RCA-2026-04-03-001: Prevention

Preventive Measures

Short-term (This week)

Action Owner Status

Investigate .zshenv / .zshrc for malformed PATH export

Evan

[ ] Pending

Add defensive PATH construction to shell init

Evan

[ ] Pending

Verify echo $PATH | tr ':' '\n' shows /usr/bin in Claude Code

Evan

[ ] Pending

Long-term

Action Owner Status

Add Claude Code shell environment validation to dotfiles

Evan

[ ] Pending

Document absolute paths for frequently used binaries in codex

Evan

[ ] Pending

Lessons Learned

What went well

  • Quickly identified the binary existed via ls /usr/bin/bluetooth*

  • Absolute path workaround resolved issue in seconds

  • Connected before the call started

What could be improved

  • Should have a pre-validated shell environment for Claude Code

  • PATH issues are silent until they bite — need a health check

Key Takeaways

  1. Exit code 127 = command not found, not command failed — Always check PATH before assuming the tool isn’t installed

  2. Claude Code shell != your terminal — The Bash tool may have a different environment than your interactive zsh session

  3. Absolute paths are the ultimate fallback — /usr/bin/command bypasses all PATH issues

  4. ls /usr/bin/command* — Fastest way to verify a binary exists when which also fails (because which itself depends on PATH)

  5. Audit shell init files — A literal $PATH in the output is the smoking gun for unexpanded variable references

Connection to RCA-2026-03-27-001

RCA-2026-03-27-001 addressed the knowledge gap (not knowing bluetoothctl commands). This RCA addresses the environment gap (knowing the command but the shell can’t find it). Together they cover both failure modes for Bluetooth CLI operations.

Related