Background tasks break serial port (device file) read operations
Resolved 💬 2 comments Opened Mar 19, 2026 by Loong0x00 Closed Apr 17, 2026
Description
When running commands in background mode (run_in_background: true), reading from serial port device files (/dev/ttyUSB*) fails, while the same code works perfectly in foreground mode.
Steps to Reproduce
- Connect a USB-to-serial adapter (CH340,
/dev/ttyUSB0) - Run a Python script that opens and reads from the serial port:
import serial, time
ser = serial.Serial('/dev/ttyUSB0', 115200, timeout=1)
ser.write(b'test') # Write succeeds
time.sleep(1)
data = ser.read(100) # Read fails in background mode
- In foreground (normal Bash tool call): works perfectly
- In background (
run_in_background: true):read()fails
Error
serial.serialutil.SerialException: device reports readiness to read but returned no data
(device disconnected or multiple access on port?)
Analysis
select()/poll()reports the fd as readable, butread()returns 0 bytes- The serial port fd is correctly opened (verified via
/proc/self/fd/→/dev/ttyUSB0) write()to the serial port succeeds- Only
read()fails - fd environment is identical in both modes: fd 0 =
/dev/null, fd 1/2 = output file, fd 3 =/dev/ttyUSB0
Environment
- OS: Arch Linux 6.19.8
- Python: 3.14
- pyserial: installed via pip
- USB adapter: CH340 (
1a86:7523) - Claude Code: 2.1.51
Impact
This affects any background task that needs to read from hardware devices (serial ports, GPIO, etc.). A specific use case: running a long XMODEM firmware transfer over serial port — the transfer needs 40-60 minutes and would benefit from background execution, but the read failure makes it impossible.
Workaround
Run device IO scripts in a separate terminal window instead of using Claude Code's background task feature.
This issue has 2 comments on GitHub. Read the full discussion on GitHub ↗