Troubleshooting

Solutions for common Lager issues

This page covers the most common issues you may encounter when using Lager, organized by category. Each section includes the error or symptom, the likely cause, and the fix.

---

Connection Issues

lager hello fails with 'No route to host'

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.

lager hello fails with 'Connection refused'

Cause: The network path to the box works, but the Lager service on the box is not running.

Fix:

1. The Docker container on the box may have stopped. Contact 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.

lager hello fails with 'Connection timed out'

Cause: The network request is being sent but not reaching the box, often due to a firewall or incorrect IP.

Fix:

1. Double-check the IP address with lager boxes.
2. If the box was recently moved or reprovisioned, its IP may have changed. Check your Tailscale admin panel or router DHCP table.
3. Try pinging the box: ping <box-ip>.

Box was working but is now unreachable

Cause: The box may have lost power, network connectivity, or had its IP address change.

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-box --ip <new-ip>.
4. Run lager hello --box <name> to check box status.

---

Instrument Detection

lager instruments returns an empty list

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. Ensure the Docker container is running with USB passthrough. Run lager hello --box <box>.
4. Run lager update --box <box> to install the latest udev rules and drivers.

A specific instrument is missing from the list

Cause: The instrument may not be recognized, may be using a different USB port, or may need updated drivers.

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.

'Resource busy' error when using an instrument

Cause: Another process (such as a TUI session or another CLI command) is actively using the instrument’s USB connection.

Fix:

1. Close any running TUI sessions (press q to exit).
2. Wait a moment and retry — the previous command may still be completing.
3. If the issue persists, the instrument handle may be stuck. Run lager update --box <box> to restart the service.

---

Power Supply Issues

OVP or OCP tripped (output disabled unexpectedly)

Cause: The output voltage or current exceeded the protection threshold you set, so 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>.

Voltage reads 0V when the supply is enabled

Cause: The supply output may not actually be enabled, or the load may be pulling 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):
   lager supply <NET> voltage 3.3 --yes --box <box>
   lager supply <NET> enable --yes --box <box>
   
3. Check if OVP/OCP tripped (see above).

---

Debug / Flash Issues

'No target detected' when flashing

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>.

'GDB server failed to start'

Cause: The J-Link or pyOCD process may be stuck from a previous session.

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

ImportError: No module named 'lager'

Cause: You are running the script directly with python instead of using lager python.

Fix: The lager Python library is only available inside the Lager Box environment. Always run scripts with:

lager python my_script.py --box my-lager-box

Do not run python my_script.py directly on your laptop.

InvalidNetError: Net 'XYZ' not found

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>.

Script runs but produces no output

Cause: The script may be failing silently, or output may not be flushed.

Fix:

1. Add print() statements to confirm the script is executing.
2. Wrap your code in try/except to catch errors:
   try:
       # your code here
   except Exception as e:
       print(f"Error: {e}")
   
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.