Troubleshooting¶
"Address already in use"¶
Another process is bound to the chosen port. Either pick a different port, or leave the port unset so a free one is auto-selected:
qrtransfer --port 9000 file
qrtransfer file # auto-selects a free port
A remembered port from a previous --port run can also cause this — pass
--force to ignore saved settings.
The QR code looks garbled or shows escape sequences¶
qrcode-terminal renders with ANSI escape codes and block characters. Use a
monospaced font in a modern terminal (Windows Terminal on Windows). If the code
still won't scan, copy the plain-text URL: line printed directly below it into
your phone browser.
The phone says the page doesn't load / wrong IP advertised¶
The advertised IP must be reachable from your phone, so both devices must be on the same network. If the detected IP looks wrong, force the interface:
qrtransfer -i wlan0 file
Diagnose with ip addr (Linux), ifconfig (macOS), or ipconfig (Windows).
Browser shows a TLS warning¶
Expected — the certificate is self-signed. Accept the warning to continue, or
re-run without --tls on a trusted network. See faq.md.
I get a 401 even though I set a password¶
The password can be supplied as ?passed=SECRET (this is what the QR code
embeds) or as the X-Password header. A mismatch returns 401. A wrong token,
however, returns 404 before the password is even checked, so a 404 may also
mean the passworded session's URL is wrong.
Uploads are rejected¶
411 Content-Length required— the client didn't send aContent-Length. Regular browsers always do.413— the upload exceeds--max-upload-size(default 1024 MB). Raise it:qrtransfer receive --max-upload-size 5000.
The session ends before I'm done¶
The default is exit-after-one-transfer. Keep it alive with --keep-alive,
--max-downloads N, or --expire SECONDS. If you set --expire, the link also
dies after the window even if the server is still running.
--clipboard doesn't copy anything¶
--clipboard needs the pyperclip package:
pip install "qrtransfer-lite[clipboard]"
Without it the tool prints a notice and continues normally.
--tls fails to start¶
Auto-generated certificates need the cryptography package:
pip install "qrtransfer-lite[tls]"
Or supply your own --cert/--key, which needs no extra dependency.
No transfers recorded in --history¶
History is written when a session ends. An empty history means no session has finished yet. Check that you're looking at the right machine/account — history is local to each computer (see configuration.md).
Still stuck?¶
Open an issue at
https://github.com/rkriad585/qrtransfer/issues
with your OS, Python version, and the qrtransfer --verbose output.