RCA-2026-04-03-001: bluetoothctl PATH Resolution Failure

Executive Summary

User needed to connect Samsung Galaxy Buds3 Pro urgently before a call. The bluetoothctl binary existed at /usr/bin/bluetoothctl but command -v bluetoothctl returned exit code 127 (command not found). Root cause: the Claude Code shell environment initializes with a malformed $PATH that contains a literal $PATH string instead of the expanded value, preventing resolution of standard /usr/bin/ binaries. Resolution: invoked bluetoothctl via absolute path /usr/bin/bluetoothctl. This RCA documents the shell environment divergence and establishes defensive patterns.

Timeline

Time Event

2026-04-03 ~AM

User requested urgent Bluetooth connection for incoming call

+10s

bluetoothctl devices returned exit code 127 — command not found

+20s

which bluetoothctl also failed (exit 127)

+30s

ls /usr/bin/bluetooth* confirmed binary exists at /usr/bin/bluetoothctl

+40s

/usr/bin/bluetoothctl devices succeeded — listed 8 paired devices

+50s

/usr/bin/bluetoothctl connect 24:24:B7:B5:1C:CC — Buds3 Pro connected

+60s

User on call, requested RCA for learning

Problem Statement

Symptoms

  • bluetoothctl returned exit code 127 (command not found)

  • which bluetoothctl also failed

  • Binary confirmed present at /usr/bin/bluetoothctl

Expected Behavior

Standard binaries in /usr/bin/ should be resolvable by name in any shell session.

Actual Behavior

The Claude Code subshell $PATH contained a literal $PATH string instead of expanded system paths:

$ echo $PATH
/home/evanusmodestus/.local/bin:/home/evanusmodestus/.cargo/bin:/home/evanusmodestus/.local/bin:$PATH

The trailing $PATH was never expanded, so /usr/bin, /usr/sbin, /bin, /sbin were missing from the search path entirely.

Impact

Severity

Metric Value

Severity

P3 (minor — workaround available)

Duration

~50 seconds to resolution

Users/Systems Affected

1 user, Claude Code shell environment

Data Loss

None

Broader Implications

This affects any Bash tool invocation in Claude Code that relies on standard system binaries by name:

  • systemctl, journalctl, ip, ss, lsblk

  • pacman, paru

  • docker, podman

  • ssh, scp, rsync

Any of these would also fail unless invoked with absolute path.

Metadata

Field Value

RCA ID

RCA-2026-04-03-001

Author

Evan Rosado

Date Created

2026-04-03

Last Updated

2026-04-03

Status

Final

Review Date

2026-05-03