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.

​
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: 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 cannot communicate with the target MCU.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 --box <box>.
Cause: A J-Link or pyOCD 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>.

​
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: 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: lager logs --box <box> shows recent log output from the box’s Docker container.
  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.