flua troubleshooting — when it doesn't work, start here

flua is usually quiet when things go well and loud when they do not. This post is the short version of the troubleshooting skill: the most common problems, what they mean, and the fix — for Windows and macOS. No programming background required.

1. First stop: one command that explains itself

Before anything else, run:

flua doctor

It checks the nine things that usually go wrong — the flua install, the Python environment, the HC3 credentials and whether the controller is reachable (without ever printing your password), the VS Code setup, and more. Each line is a ✓ or ✗ with the reason. If doctor is all green and something still fails, the sections below cover the usual suspects.

2. "online mode requires HC3_URL"

flua: error: online mode requires HC3_URL (or HC3_HOST) in the environment

flua runs offline against a simulated HC3 by default — no controller needed. This error means something asked for the real controller: --api remote on the command line, or --%%mode:online / --%%mode:proxy in the QA file's header — but flua could not find the controller's address.

Two fixes:

• Put the address and credentials in a .env file (in the project folder, in your home folder, or as environment variables): HC3_URL, HC3_USER, HC3_PASSWORD.
• Or run offline on purpose: flua --api local myqa.lua, or --%%mode:offline in the QA header.

3. Wrong password? The HC3 locks itself

If the credentials are wrong, flua stops immediately instead of retrying — the HC3 locks itself after 4 failed attempts, and flua will not burn those on your behalf. Fix the password in .env, wait for the lock to clear, and run again: exactly one attempt was spent.

4. flua --version crashes after an upgrade

Symptom: you upgraded flua, something went wrong, and now every command dies with a Python traceback like:

ImportError: cannot import name '__version__' from 'flua'

What happened: the upgrade was interrupted halfway — often a running flua process (or an antivirus scan) locked files on Windows — so the install folder now holds a mix of new and old files. Re-running the upgrade says "all requirements already satisfied", because pip only compares version numbers, not files.

The fix is a forced reinstall. Close all flua windows and VS Code debug sessions first, then:

python3 -m pip install --upgrade --force-reinstall --no-cache-dir fibaro-flua

On Windows, use python -m pip ... and add --user if your error path mentions AppData\Roaming\Python (that is the "user install" location — it must match how you installed flua the first time). --force-reinstall overrides "already satisfied", and --no-cache-dir rules out a corrupted download. Verify with flua --version.

5. Proxy mode: the device is on the HC3, but buttons do nothing

Proxy mode (--%%mode:proxy) runs your QA on the laptop while the device lives on the HC3. Button presses travel from the HC3 back to your computer — so two things must be true:

• flua is running. The proxy posts every press to your computer. If flua is not running, those posts go nowhere — and they are not buffered, so presses during downtime are lost. Start flua, then press again.
• The HC3 can reach your computer. flua listens on port 8080 and tells the controller where to call back. When the connection is set up, the log shows the address — check it:

flua: proxy connected — MyQA_Proxy (57) sends actions and UI events to http://192.168.1.23:8080

The IP must be your computer's real network address. On Windows compare with ipconfig, on macOS with ipconfig getifaddr en0. If it shows a VPN or virtual-machine address instead, that is the problem: the HC3 cannot route to it. (Running flua inside WSL on Windows has the same effect — run it in normal Windows Python.)

If the address looks right but presses still do nothing, it is almost always the firewall — the most common cause on both systems, because everything flua sends works while everything incoming is silently blocked:

• Windows. Windows Firewall only shows the "Allow access?" prompt when your network is classified Private. If it is Public (Windows changes this silently after network changes), incoming connections are blocked without any prompt. Fix: Windows Security → Firewall & network protection → Allow an app through firewall → find Python → allow on Private networks. Or add a rule from an admin PowerShell:

netsh advfirewall firewall add rule name="flua proxy" dir=in action=allow protocol=TCP localport=8080

The rule belongs to one Python installation — a new venv or a new Python version needs its own. Change the port with FLUA_PROXY_PORT in .env if 8080 is taken (flua silently moves to the next free port — the log line above always names the real one).

• macOS. The first time flua's proxy server starts, macOS asks "allow Python to accept incoming network connections?" — if that was denied (or never appeared), open System Settings → Network → Firewall → Options and allow the Python entry (remove it and re-add if it is stuck on blocked). Make sure "Block all incoming connections" is off.

Quick test for both systems: while flua runs, open http://<your-ip>:8080/ in a browser on your phone (same Wi-Fi). Any answer — even "not found" — proves the network path is open; a timeout means the firewall (or the router's Wi-Fi client isolation) is still in the way. To see whether flua is listening: on Windows netstat -ano | findstr :8080, on macOS lsof -nP -iTCP:8080 -sTCP:LISTEN.

6. The run ends right away

flua exits when nothing is pending — no timers, no messages, no connections. A QA that just waits for HC3 events needs to say so: --%%keep-alive:true in the header (proxy QAs do this automatically), or run with flua --run-for 0 / flua --ui to stay alive while you experiment.

7. Odd warnings about directives and device types

WARNING flua.config: unknown --%% directive: --%%instnat:true

That is a typo in a --%% header line (here: instant). flua parses it anyway and warns at runtime; flua --check myqa.lua reports it with the file name. And if startup fails with unknown device type, the error names the closest matches — the full list of supported types is one command away:

flua --tool catalog

8. Still stuck? The diagnostic loop

Three things, in order:

• flua --check myqa.lua — static problems, named and located.
• flua --log json myqa.lua — one JSON object per log line, easy to search; and the engine keeps its own diary at http://localhost:<ui-port>/flua/systemLog when the viewer runs.
• Your QA's own self:debug("...") lines — plus --%%debug:refreshState=true,api=true,http=true,ws=true in the header to see every event and API call the emulator sees.

If you work with an agent (Claude, Copilot, …), point it at the flua-troubleshooting skill — it carries the deeper sections (bridge errors, virtual-time surprises, the debugger) with the exact remedies.