← All news

Meet qrcp doctor: find out why your phone can't connect

Published on

The most common qrcp problem is easy to describe: the QR code scans, the browser opens, and then the page never loads. The cause is almost always on the computer: qrcp picked a Docker bridge instead of the Wi-Fi, a firewall blocks the port, a VPN is in the way. Until now, finding which one meant guessing.

qrcp v0.12.0 adds a command that does the guessing for you:

qrcp doctor

What it does

doctor looks at this computer’s network setup the same way send and receive would, and reports every problem it finds with a suggested fix. It checks:

Each check is reported as ok, info (couldn’t be fully checked), warn (likely to cause problems) or fail (transfers won’t work until it’s fixed).

Here’s a typical case, on a machine where qrcp was configured to use the Docker interface by mistake:

$ qrcp doctor -i docker0
Network interfaces:
   docker0          172.17.0.1               virtual
   lo               127.0.0.1                loopback
 * wlan0            192.168.1.81             wifi
   (* looks connected to the local network)

[warn] interface using docker0 (172.17.0.1, virtual): it looks like a virtual interface (Docker, VM, bridge), which a phone usually can't reach
                 -> use --interface wlan0, or set it with `qrcp config`
[  ok] port      a random port is used for each transfer
                 -> if a firewall blocks incoming connections, set a fixed port with --port or `qrcp config`, and allow it once

The problem and the fix, in one line each.

What you can use it for

“The phone can’t open the link.” This is the main use: run qrcp doctor before anything else, and follow the hints. It takes a second and doesn’t touch anything.

Checking a setup before you need it. doctor takes the same flags as send and receive, so you can test an exact setup in advance: before a demo, on a new laptop, or on the hotel or conference network.

qrcp doctor -i wlan0 -p 8080 --secure --tls-cert cert.pem --tls-key key.pem

Machines with many interfaces. Docker, virtual machines and VPN clients add interfaces that a phone can’t reach. doctor tells you which one is the real local network, so you can save it once with qrcp config.

Firewalls. By default qrcp uses a random port, which most firewalls block. doctor points this out and suggests a fixed port to allow once.

WSL 2. With the default NAT networking, qrcp inside WSL can’t be reached from other devices. doctor detects WSL and explains how to switch to mirrored networking.

HTTPS setups. With --secure, it checks that the certificate and the key exist and can be loaded, before the phone sees an error page.

Better bug reports. If you still can’t connect, paste the output of qrcp doctor in a new issue. It answers most of the questions we would ask you anyway.

Scripts and AI agents. qrcp doctor --json prints the same report as JSON, and the command exits with code 1 when a check fails. A script can stop before starting a transfer that can’t work, and an AI agent can read the report and fix the configuration for you:

qrcp doctor --json | jq -r '.checks[] | select(.status == "fail" or .status == "warn") | .hint'

What it can’t do

doctor only checks this computer. It can’t test the phone, and it can’t see whether the Wi-Fi network blocks devices from talking to each other, which many guest networks and public hotspots do. A clean report doesn’t guarantee the phone can connect, but it rules out the most common causes. If the phone still can’t connect, try another network or the phone’s hotspot.

It also never prompts and never changes your configuration: it only reports.

Try it

qrcp doctor is available from v0.12.0. Update with your package manager, then read the troubleshooting guide for the full list of options and common causes.