Symptoms & Diagnosis
The “hci0 not found” error typically occurs when a Docker container lacks the necessary permissions or hardware access to interact with the host system’s Bluetooth controller. You might encounter this while attempting to use BlueZ or Bluetooth-based applications inside a containerized environment.
Common symptoms include the hciconfig command returning an empty list or error messages such as “Can’t open HCI socket” or “Address family not supported by protocol.” This indicates that the virtualized environment is isolated from the physical hci0 interface.
| Symptom | Probable Root Cause |
|---|---|
| hciconfig shows no devices | Hardware interface not mapped to container |
| Operation not permitted | Missing –privileged flag or capabilities |
| D-Bus connection refused | BlueZ daemon communication failure |
Troubleshooting Guide
Step 1: Verify Host Bluetooth Status
Before modifying Docker settings, ensure the host machine identifies the adapter. Run the following command on the host terminal:
hciconfig -a
ls /sys/class/bluetooth/If hci0 does not appear here, the issue is with your host drivers or the physical hardware, not Docker.
Step 2: Use Host Networking and Privileged Mode
Docker containers are isolated by default. To allow access to the Bluetooth stack, you must use the host’s network stack and grant privileged access to the hardware devices.
docker run --privileged --net=host -it ubuntu:latest /bin/bashStep 3: Mount the D-Bus Socket
Most modern Bluetooth applications rely on D-Bus to communicate with the BlueZ daemon. You must mount the host’s D-Bus socket into the container for hci0 to be manageable.
docker run --privileged \
--net=host \
-v /var/run/dbus:/var/run/dbus \
-it your-bluetooth-imageStep 4: Configure Docker Compose
If you are using Docker Compose, ensure your docker-compose.yml includes the necessary volumes and network modes to expose the Bluetooth interface.
services:
bluetooth-app:
image: custom-bluez-app
network_mode: "host"
privileged: true
volumes:
- /var/run/dbus:/var/run/dbusPrevention
To prevent future “hci0 not found” errors, ensure that the BlueZ service is active on the host before starting the container. Docker cannot map a hardware interface that is currently down or being initialized by the kernel.
Consider creating a custom Dockerfile that installs bluez and dbus packages internally. This ensures the container has the required binaries to interact with the mounted volumes.
Lastly, always verify that the user running the Docker container has the appropriate permissions to access the /dev/bus/usb or /dev/vhci nodes if you prefer not to use the --privileged flag for security reasons.