> For the complete documentation index, see [llms.txt](https://delta-robotics.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://delta-robotics.gitbook.io/docs/help/troubleshooting.md).

# Troubleshooting

Fix the common ThermoFlex failures, from a Node that isn't found to a muscle that won't contract, with the cause and the fix for each symptom

Find your symptom below. Each section names the likely cause, then gives the fix.

{% hint style="info" %}
Most first-run problems are the USB connection, the driver, or a muscle that was never enabled. Work down this list in order and you'll clear the majority of them.
{% endhint %}

## No Node found on startup

Discovery raises `ImportError: No Thermoflex nodes found on available USB ports`, or `get_usb_node()` raises `TimeoutError` after a few seconds.

**Likely cause.** The Node isn't reachable over USB: a charge-only cable, a flaky port, a missing driver, or a Node with no power.

**Fix.**

* Use the data USB-C cable from the kit, not a charge-only cable.
* Try a different USB port, ideally one directly on the computer.
* Confirm the Node is powered and its LED is on.
* On Windows, confirm the driver is installed (see the next section).
* Replug the Node and run the script again.

## Node not listed in Device Manager (Windows)

The Node doesn't appear under **Ports (COM & LPT)** as **USB Serial Device (COMx)**, or it shows a yellow warning icon.

**Likely cause.** Windows hasn't loaded the serial driver for the Arduino Uno R4 Minima the Node is built on.

**Fix.** Follow the driver steps on [Set up software and drivers](/docs/tutorials/thermoflex/getting-started-with-our-evaluation-kit/update-library-and-firmware.md): let Windows Update finish, or install the Arduino IDE driver package, then unplug and replug the Node. On macOS and Linux, no driver is needed; the Node appears as a serial device.

## Muscle does not contract

The script runs without errors, but the muscle stays still.

**Likely cause.** The muscle was never enabled, the setpoint is zero, the control mode is wrong, or the power supply can't deliver enough current.

**Fix.**

* Call `muscle.setEnable(True)` after setting the mode and setpoint.
* Set a nonzero setpoint, for example `muscle.setSetpoint("percent", 0.5)`.
* Set the mode first with `muscle.setMode("percent")` so the setpoint is interpreted correctly.
* Check that the battery or supply is connected, charged, and delivering enough current for your wire diameter.

## The Node disables itself mid-run

The muscle drops power partway through a session, even though your script hasn't told it to stop.

**Likely cause.** The Node expects a regular heartbeat from the host. The library sends one about every 2 seconds. If the host stops talking for longer than that (a blocked or paused script, a suspended process), the Node disables its outputs as a safety measure.

**Fix.** Keep the session alive: don't block the main thread for long stretches, and keep the program running while the muscle is active. Call `tf.endAll()` only when you're actually done, not between commands.

## Firmware-version warning on discovery

On startup the library prints a warning that the Node firmware is outdated, or newer than tested.

**Likely cause.** The 1.0.2 library is tested against TF Node Controller firmware 1.1.1 to 1.1.2. A Node outside that window triggers the warning.

**Fix.** Update the Node to a firmware version in the supported window. See [Firmware updates](/docs/software/firmware-updates.md). The warning alone won't stop the script, but running outside the tested range can cause unexpected behavior.

## Serial port busy or access denied

Discovery or a command fails with a `SerialException` about the port being in use or access being denied.

**Likely cause.** Another program is holding the serial port: an Arduino IDE Serial Monitor, a second terminal or script, or a previous run that never called `tf.endAll()`.

**Fix.**

* Close any Serial Monitor or IDE that has the port open.
* End stray Python processes from earlier runs.
* Unplug and replug the Node, then run the script again.
* On Linux, make sure your user is in the `dialout` group.

## Related pages

* [Set up software and drivers](/docs/tutorials/thermoflex/getting-started-with-our-evaluation-kit/update-library-and-firmware.md): driver and install steps.
* [Firmware updates](/docs/software/firmware-updates.md): flash a supported firmware version.
* [FAQ](/docs/help/faq.md): quick answers to common questions.
* [Known limitations](/docs/help/known-limitations.md): what to expect from the current release.