TetherBox Troubleshooting
https://my-company.timeline.is/help/tetherboxes/troubleshooting
Last updated: November 22, 2026
Table of Contents

TetherBox Troubleshooting

Open Admin → TetherBoxes and check the Health column. Online units show a health badge with an information popover listing current issues; offline units show when they were last seen. Open the affected unit for its CPU, memory, temperature, drive, network and device details.

The Issues total counts online units with Warning or Critical health across the filtered list, including units on other pages. Each unit counts once. Offline units have their own total.

What you see What to do
TetherBox is offline Follow TetherBox Went Offline for power and network checks.
Drive Health warning or error Check the Storage tab and drive-and-stress-test-failures.
High CPU, load, IO wait or temperature Check performance-and-temperature.
Latency, packet loss or interface error Check network-connection.
A camera is offline or has recording problems Follow Camera Troubleshooting.
Stuck at Starting, Updating or Restarting Follow TetherBox States.
TetherBox service stopped, a recording or detection service failed, or detection is off for lack of memory, unsupported hardware or refused cameras Read the named service, memory figures or camera reasons in the health popover, then restart the TetherBox or reduce the cameras using detection. Contact support if it persists.

Enable the Health Report for a regular summary of TetherBox and camera issues in your notification settings.

Tip: Use the Health Report to identify recurring drive, network or reboot problems before they interrupt recording.

 Read the Status Page

The status indicators at the top of a TetherBox page

Indicator Meaning
Online status Connection to TetherX. Open the badge for details.
Health All current system, storage, network and connected-device warnings.
Drive health SMART errors, write failures, drive age and probe results.
Latency/loss Round-trip time and packet loss to TetherX.
Local capacity Estimated recording days before the oldest footage is overwritten.
Cloud backup Backup and synchronisation health.

Red needs prompt attention. Yellow indicates a condition to investigate before it affects recording. Custom or repurposed hardware should first be checked against Hardware Specifications for CPU, RAM, cooling and storage suitability.

Warning: A custom or repurposed host can pass a basic check yet still be undersized for its camera count. Confirm CPU, RAM, cooling and storage before treating the issue as a software fault.

 Drive and Stress-Test Failures

Drive Health reports the immediate condition of recording storage. A SMART error, failed probe, I/O error or ejected drive means recordings may be at risk. An ejected drive is not always a failed drive: the Storage tab history says why the TetherBox ejected it (for example, no I/O completed in 15 seconds, the USB bridge involved, the SMART result and any recovery it tried), and a USB bridge fault can look like a dead drive. Open the Storage tab for drive details and logs, check the cable or enclosure, then replace unreliable storage. See Storage and Storage Hardware Recommendations.

Health popovers explain recording-storage problems and link to Storage for the findings. A hard disk's age alone does not mean it has failed and does not raise a Health warning. Staff can see age-planning notes in the Storage tab's staff details; actual read errors, media faults and reported SSD wear still raise warnings.

The stress test checks memory, then puts the CPU, memory and storage under load. The default is four hours. Choose five minutes for a quick check of a smaller memory sample, or eight hours for a longer test.

If the memory check times out before completing a pass, run a longer test. If the test reports errors, use the details to identify the component to investigate.

  1. Re-run an interrupted test from the Settings tab.
  2. Read the first line of Error Details to identify CPU, memory or I/O.
  3. Test or replace faulty RAM, power supply, drive, cable or enclosure.
  4. Check cooling and reset aggressive BIOS settings on custom hardware. BIOS Settings lists the values a TetherBox should have.

A stress test that failed, with its error details

A passing test means that the tested memory passed verification and the load phase completed without errors. Use CPU Recommendations to check whether the TetherBox has enough capacity for its cameras.

 Performance and Temperature

Metric Normal Investigate Critical
CPU or memory Under 80% 80-90% Above 90%
Load Under 2.3 2.3-3.5 Above 3.5
IO wait Under 15% 15-20% Above 20%

The performance readings on a TetherBox page

High CPU or load usually means too many cameras, unnecessarily high stream resolution or bitrate, or AI running without suitable hardware. Compare the host with CPU Recommendations and Hardware Specifications, then reduce stream demand or add capacity.

IO wait and drive load mean the processor is waiting for storage. Check drive health, free capacity, write speed, cabling and the enclosure. Avoid SD cards, USB sticks, SMR drives and low-quality USB adapters for continuous recording. High-camera-count sites need suitable NVMe or RAID storage. See Storage Hardware Recommendations.

Overheating reduces performance and can cause recording gaps or stress-test failures. Improve airflow, remove dust, keep the unit away from direct heat and ensure cooling matches the workload. Raspberry Pi 5 uses the official 27 W USB-C supply. If CPU temperature rises steadily under normal demand, fit active cooling or use a more capable host.

Warning: Sustained CPU, memory, IO-wait or temperature alerts can create recording gaps and delayed uploads. Investigate yellow and red health warnings promptly.

 Network Connection

The Latency/Loss badge measures the route between the TetherBox and TetherX. Any packet loss is worth investigating. Use the Network tab to check interface speed, duplex, link state and error counters.

  • Replace the patch lead and test another switch port if an interface reports Bad Cable or Half Duplex.
  • Resolve packet loss, high latency or a slow link before diagnosing recording gaps as a software issue.
  • Gigabit networking is recommended for sites with more than five cameras.

The Network tab, with each interface's speed, duplex, link state and error counters

Network health check

The Network health check is off by default. When it is on, the TetherBox listens to the local network for about a minute every hour and reads switch counters (SNMP) to look for cable faults, loops, flooding and IP address conflicts. It sends the result to TetherX with its regular heartbeat. Staff who are allowed to change the Disable Network Scanning setting can switch it on or off in the TetherBox's Settings tab, under Network health check. This is separate from network scanning, which controls device discovery.

Once a TetherBox has sent a report, its Network tab shows a Network health check card:

  • The time of the last check appears beside the title. If the TetherBox has not reported a recent check, an Out of date: the TetherBox has not reported a recent check badge appears. TetherX treats a report as current for six hours, so an out-of-date report may mean the TetherBox is offline or the check has stopped.
  • The table lists each Finding, Where it was seen and the Evidence. If nothing was found, the card says No faults found on the local network.
  • The Checks list shows each check and whether it Ran, was Not run, was Not present, Needs a login, Needs configuring, was Unavailable or Partly ran. A short reason may follow.

Findings that need action come first and are highlighted while the report is current. They also appear in the TetherBox's Health warnings as Network fault. Use the table below to decide what to check.

Finding What to check
Switch port errors during the check, or errors on the network link Replace the patch lead on the port or interface named in Where, and test another port.
Half-duplex link, or switch port at half duplex Check the cable and the speed and duplex settings on both the TetherBox port and the switch port, as the two ends should agree.
IP address conflict Find the two devices using the address in the evidence and give one a different address, or a DHCP reservation.
Several spanning-tree root switches Check the switch settings, because the network should have one spanning-tree root. Look for switches that are not connected to each other as intended.
Packet loss to the gateway Check the cable, switch port and router that connect the TetherBox to its gateway.
Unicast flooding Check the switches between the TetherBox and the devices that are flooding, for faults or settings that stop them learning addresses.
Network loop (traffic echoed back) Look for a cable that connects two ports of the same network, or switches joined by more than one cable.
Network link keeps dropping Check the cable, connectors and switch port for a loose or damaged connection.

Other findings are shown without highlighting and do not raise a Health warning. They describe conditions such as a slow link, a link heavily used, high broadcast, multicast or ARP traffic, high TCP retransmissions, powerline or mesh devices, several IP addresses behind one MAC address, or a switch that could not be read. Treat them as context when you are diagnosing recording gaps or slow uploads. A finding named Unrecognised followed by a name is one that this version of TetherX has no wording for yet; quote the name to Support.

 Collect Information for Support

If the status page does not identify the fault:

  1. Check the Reboots, Connections, Updates and USB tabs.
  2. Record the TetherBox serial number, error messages and unusual readings.
  3. Send TetherX support screenshots of the relevant status and detail panels.

USB Devices and SMART Details

On the TetherBox page, open Devices > USB to inspect attached devices, their mount points and block device paths. Refresh reloads the list. USB reset, power and eject actions can interrupt a recording drive; check the device before using them.

USB devices, mount points and controls

Open Storage and scroll to the SMART health analysis for drive attributes and their reported values. Some USB enclosures do not expose SMART attributes; missing SMART data alone does not confirm a drive fault.

SMART attribute values from a captured drive report

Last updated: November 22, 2026