Skip to main content
This page covers the most common problems in Lager, grouped by category. Each section gives the error or symptom, the likely cause, and the fix.

​
Connection Issues

Cause: Your computer cannot reach the Lager Box on the network.Fix:
  1. Verify your VPN is connected: run tailscale status and confirm your Lager Box appears in the list.
  2. Check the IP address is correct: run lager boxes to see your saved box IPs.
  3. If using Tailscale, try ping <box-ip> to verify network connectivity.
  4. Ensure the Lager Box is powered on and connected to the network.
Cause: The network path to the box works, but the Lager service on the box stopped.Fix:
  1. If the Docker container on the box stopped, ask your administrator to restart it.
  2. Run lager hello --box <box> to check the box’s service status.
  3. If you have SSH access, connect to the box and check Docker: docker ps | grep lager.
  4. If nobody set the machine up as a Lager Box, see Setting Up a Lager Box.
Cause: The network request leaves your computer but does not reach the box. A firewall or an incorrect IP usually causes this.Fix:
  1. Double-check the IP address with lager boxes.
  2. A box that moved or changed provisioning can have a new IP address. Check your Tailscale admin panel or your router DHCP table.
  3. Try pinging the box: ping <box-ip>.
Cause: The box lost power, lost network connectivity, or changed its IP address.Fix:
  1. Verify the box is powered on.
  2. Check your VPN connection: tailscale status.
  3. If the box IP changed, update it: lager boxes edit --name my-lager-box --ip <new-ip>.
  4. Run lager hello --box <name> to check box status.
Cause: The box does not accept any SSH key that lager ssh offers.lager ssh offers ~/.ssh/lager_box first. It then offers each default key that exists: id_rsa, id_ecdsa, id_ed25519 and their -sk versions. It also offers the keys in your ~/.ssh/config and your SSH agent.Fix:
  1. Run lager ssh-setup --box <box>. Enter the box password once when it asks.
  2. Retry lager ssh --box <box>.
  3. If you use a box IP address in --box, lager ssh logs in as lagerdata. Use the saved box name to log in as the saved user.
  4. If your CLI is older than 0.45.1, upgrade it. When lager_box exists, an older lager ssh offers only that key.

​
Instrument Detection

Cause: No instruments are detected on the box’s USB ports.Fix:
  1. Verify instruments are physically connected via USB to the Lager Box (not to your laptop).
  2. Check that USB cables are properly seated — try a different cable or port.
  3. Confirm that the Docker container runs with USB passthrough. Run lager hello --box <box>.
  4. Run lager update --box <box> to install the latest udev rules and drivers.
Cause: The box does not recognize the instrument, or the instrument uses a different USB port. The drivers can also need an update.Fix:
  1. Unplug and replug the instrument’s USB cable.
  2. Run lager update --box <box> to ensure udev rules are current.
  3. Check that the instrument is powered on (some instruments need external power in addition to USB).
  4. Verify the instrument model is supported.
Cause: The box probes a serial port for an arm only when the port has the USB ID 0483:5740. The arm must also answer the probe and report a USB serial number.Fix:
  1. Read the result of the last probe from the box log:
  2. Find the port of the arm in the skipped list. The reason next to it tells you why the box skipped it.
  3. If the reason is not a Dexarm vid:pid, the arm reports a different USB ID. Set the probe to force:
  4. Run lager instruments --box <box> again.
  5. When the arm appears, remove the setting with lager box-config env unset LAGER_ARM_PROBE --box <box>. Then run lager box-config apply --box <box>.
If a board on the box resets when its DTR or RTS line changes, do not use force. The force probe asserts DTR on every free serial port, which can reset that board.
See Robot Arm detection.
Cause: Another process (such as a TUI session or another CLI command) actively uses the instrument’s USB connection.Fix:
  1. Close any running TUI sessions (press q to exit).
  2. Wait a moment, then retry. The previous command can still be running.
  3. If the problem continues, the instrument handle is stuck. Run lager update --box <box> to restart the service.

​
Power Supply Issues

Cause: The output voltage or current went past the protection threshold you set. The supply shut off to protect your device.Fix:
  1. Check the current state: lager supply <NET> state --box <box>.
  2. Clear the fault: lager supply <NET> clear-ovp or lager supply <NET> clear-ocp.
  3. Adjust your protection thresholds if they are too tight, or investigate why the output exceeded the limit.
  4. Re-enable the output: lager supply <NET> enable --box <box>.
Cause: The supply output is not enabled, or the load pulls the voltage down.Fix:
  1. Verify the output is enabled: lager supply <NET> state --box <box> — check that “Enabled” shows ON.
  2. Confirm you set both the voltage and enabled the output (setting voltage alone does not enable it):
  3. Check if OVP/OCP tripped (see above).

​
Debug / Flash Issues

Cause: The debug probe did not attach to the target MCU. The command exits 1.flash can also print The target was NOT programmed. If flash ran without --no-erase, the target can be erased. A failed erase before programming prints Flash erase failed: instead, and flash does not program the target.Fix:
  1. Verify the SWD/JTAG wiring between the debug probe and your DUT.
  2. Ensure the DUT is powered (the debug probe does not always supply power).
  3. Check that the MCU type in the debug net matches your actual device: lager debug <NET> status --box <box>.
  4. Try a lower SWD speed: lager debug <NET> gdbserver --speed 100 --force --box <box>.
Cause: A JLinkGDBServer or OpenOCD process from an earlier session is stuck.Fix:
  1. Disconnect any existing session: lager debug <NET> disconnect --box <box>.
  2. Retry: lager debug <NET> gdbserver --box <box>.
  3. Check the debug probe health: lager debug <NET> health --verbose --box <box>.
Cause: The GDB server for the probe runs, but the target MCU does not answer. Usually the target lost power, or the SWD wiring came loose. The CLI prints this before flash, erase or reset, then starts a new session.Fix:
  1. If the command then prints Reconnected!, no action is necessary.
  2. If the command prints Error: the CLI did not reconnect to the target, it exits 1. Check the power and wiring of the DUT.
  3. Run lager debug <NET> status --box <box>. Confirm that Target attached reads Yes before you retry.

​
UART Issues

Cause: Another session holds the UART net or its serial device.Fix:
  1. List the sessions that hold UART nets:
  2. Read the Client column. A gone client releases the net on its own. A connected client belongs to somebody, so check with that person first.
  3. A client whose computer went to sleep or lost its VPN still reads connected for about 85 seconds.
  4. To release the holder and connect, run lager uart <net> --force --box <box>.
If the error says (locked by another session or the lager uart CLI), another process holds the serial port. A running lager python script that opened the port is one example. --force does not release that lock. Stop the script, for example with lager python --kill-all --box <box>.The --sessions and --force options take the box lock. If another user holds the box lock, both fail with is locked by.

​
Python Script Issues

Cause: You run the script directly with python instead of lager python.Fix: The lager Python library is only available inside the Lager Box environment. Always run scripts with:
Do not run python my_script.py directly on your laptop.
Cause: The net name in your script does not match any net configured on the box.Fix:
  1. List available nets: lager nets --box <box>.
  2. Check for typos in the net name. Net names are case-sensitive.
  3. If the net doesn’t exist, create it using lager nets tui --box <box>.
Cause: Two things opened a session against the same instrument. The hardware service on port 8080 owns an instrument’s VISA session. A second pyvisa open against the same USB address races it and loses.Ordinary scripts do not reach this. A supply, scope, battery simulator, e-load or solar simulator is proxied to the hardware service, not opened locally. You reach the failure by importing a driver module directly. You also reach it by opening pyvisa yourself, in a script or a docker exec.Fix:
  1. Drive the instrument through its net rather than its driver module:
  2. Check what already holds the address with lager diagnose <net> --box <box>. A VISA section that reports REACHABLE (shared session) means the hardware service holds it and skipped its own probe. See lager diagnose.
  3. To open the instrument yourself, take the same cross-process lock the drivers take.
Direct-USB instruments are a different case: LabJack, USB-202, FT232H, Aardvark, Joulescope and PPK2. The execution service releases the hardware service’s claims on those before it spawns your script.
Cause: The script fails silently, or the script does not flush its output.Fix:
  1. Add print() statements to confirm that the script executes.
  2. Wrap your code in try/except to catch errors:
  3. Check stderr output — errors from the box are shown in red in the terminal.

​
Getting More Help

If the solutions above don’t resolve your issue:
  1. Check box logs: The services on the box write their logs inside the lager container. For an instrument call that failed, read the hardware service log:
    Other logs in the container are /tmp/lager-debug-service.log, /tmp/lager-python-service.log and /tmp/lager-http-server.log. A failed instrument call returns only a one-line error to your script. The full traceback is in the log.
  2. Check box status: lager hello --box <box> verifies the box is online and responsive.
  3. Open an issue: Report problems on GitHub with your box name, the command you ran, and the error output.