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

  1. Connect a USB-to-serial adapter (CH340, /dev/ttyUSB0)
  2. 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
  1. In foreground (normal Bash tool call): works perfectly
  2. 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, but read() 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.

View original on GitHub ↗

This issue has 2 comments on GitHub. Read the full discussion on GitHub ↗