ETTerms/docs/runbooks/troubleshooting.md

ETTerms — Troubleshooting Runbooks

Serial Port Issues

COM port is busy / cannot open

Symptom: "Access to the port 'COMx' is denied" or "The port is already in use."

Cause: Another application (or another ETTerms tab) already has the port open.

Fix:

1. Check if another terminal (PuTTY, TeraTerm, Device Manager) has the port open — close it.
2. In ETTerms, only one session per COM port is allowed. Close the existing tab first.
3. If the port is stuck, unplug/replug the USB-Serial adapter.

COM port not showing in Quick Connect

Symptom: The port exists in Device Manager but ETTerms doesn't list it.

Fix:

1. Close and reopen the Quick Connect dialog (it scans on open).
2. Check Device Manager → Ports (COM & LPT) for the actual COM number.
3. Some USB adapters need drivers (FTDI, CH340, CP2102).

---

SSH Issues

Host key fingerprint changed

Symptom: "Host key mismatch" warning when connecting.

Cause: The remote server was reinstalled or its SSH keys were regenerated.

Fix:

1. Verify with the server admin that the key change is legitimate.
2. Delete the old fingerprint from %LocalAppData%\ETTerms\known_hosts.json.
3. Reconnect — ETTerms will prompt to trust the new key.

SSH connection timeout

Symptom: Connection hangs for 30+ seconds then fails.

Fix:

1. Verify the host is reachable: ping <host> from cmd.
2. Check if SSH port (default 22) is open: Test-NetConnection <host> -Port 22 in PowerShell.
3. Firewall / VPN may be blocking. Try from a different network.

---

Script (TTL) Issues

Script hangs on wait

Symptom: Script shows "wait 'xxx'" indefinitely.

Cause: The expected keyword never appears in the output stream.

Fix:

1. Press ■ Stop to cancel the script.
2. Check that the wait keyword matches exactly (case-sensitive, including spaces).
3. Use timeout = 10 at the top of your script to auto-fail after 10 seconds instead of waiting forever.
4. Use flushrecv before wait if there might be stale data in the buffer.

Script error: "'waitall' can only be used in Group execution mode"

Symptom: Script stops immediately with this error.

Cause: You used waitall, sendlnall, or sendlngroup commands but ran the script via ▶ Script (per-tab) or ▶ Run All instead of ▶ Group.

Fix:

1. Right-click the session tabs → assign them to a Group (1/2/3).
2. Use the ▶ Group1/2/3 buttons in the toolbar to run the script.

---

PDU Issues

pduconnect fails

Symptom: [pduconnect] failed to connect to <ip>

Fix:

1. Ping the PDU IP from your machine.
2. Verify the PDU is an iPoMan II/III model (SNMP v1, community "private").
3. Check that SNMP port 161/UDP is not blocked by firewall.

pductrl returns FAILED

Symptom: [pductrl] device X port Y ON → FAILED

Fix:

1. Ensure you called pduconnect first for that device number.
2. Verify the port number is valid (1–12).
3. Check PDU web interface to confirm port is not locked.

---

General

Settings not persisting

Fix: Settings are saved to %LocalAppData%\ETTerms\settings.json. Check that the folder is writable. If the file is corrupted, delete it and restart ETTerms (defaults will be recreated).

Window position not remembered

Fix: Window position saves on close. If ETTerms is killed (Task Manager), position won't be saved. Close normally via the X button.