Table of Contents
TetherBox Troubleshooting
This guide helps you diagnose TetherBox issues using the status page. Go to Admin → TetherBoxes → click your unit to view diagnostics.
Tip: The status page shows real-time system health, drive status, network performance, and resource usage. Most issues can be identified here before contacting support.
Tip: Enable the Health Report to receive regular email summaries of issues across all your TetherBoxes and Cameras. Configure frequency in your notification settings.
Warning: Custom-built TetherBoxes — verify hardware first. Units purchased directly from TetherX are pre-validated and sized for the cameras shipped with them. If your TetherBox was self-built, supplied by a third party, or repurposed from existing hardware, compare CPU, RAM, storage, and cooling against Hardware Specifications before assuming a software fault. Most stress test failures, high CPU/load, IO wait, and overheating issues on custom builds trace back to undersized or unsuitable hardware for the connected camera count.
System Status
The top section shows six key health indicators:
| Indicator | What It Shows |
|---|---|
| Online Status | Connection to TetherX cloud - green (healthy), yellow (online with issues), red (offline). Click for details. |
| Health | Overall system health - Good, Warning, or Critical |
| Drive Health | Storage drive status - age, errors, or warnings |
| Network | Latency and packet loss to TetherX servers |
| Local Capacity | Estimated days of recording before oldest footage is overwritten |
| Cloud Backup | Cloud recording status and sync health |
Warning: Red badges indicate issues requiring immediate attention. Yellow badges are warnings that may be serious and should be investigated.
TetherBox is Offline
If your TetherBox shows as offline, see TetherBox Went Offline for step-by-step diagnosis including power checks, network testing, and how to submit an offline report with boot video.
Drive Issues
The Drive Health indicator shows:
- Errors (red) - Confirmed drive faults detected via SMART monitoring. Replace the drive.
- Warning (yellow) - Potential issues detected. Monitor closely and plan replacement.
- Check Logs (yellow) - System logs show I/O errors though SMART reports healthy. Investigate further.
- Ejected (red) - Drive stopped responding and was forcibly ejected. Check connections or replace drive.
- Age - Drives over 3 years show yellow, over 4 years show red.
Tip: Click the Drive Health badge to see detailed tooltips. Open the Storage tab for full drive information including SMART data and error logs.
See Storage for drive setup and replacement guidance.
Stress Test Failed
The Stress Test drives the CPU, memory, and storage with verified workloads for about 5 minutes. Each workload performs computations and read/write cycles whose results are checked for correctness, so the test is looking for hardware faults and silent data corruption — not whether the TetherBox is fast enough for your cameras.
A failure means the test detected one or more of:
- CPU compute errors - a core returned a wrong result for a deterministic calculation (silent data corruption, marginal silicon, undervolting).
- Memory integrity errors - bits flipped in RAM during the run.
- Storage integrity / CRC errors - data read back from the drive did not match what was written.
- Crashes or hangs - a worker was killed or the kernel logged errors during the run.
You can re-run the test from the Settings tab of the TetherBox page (staff and integrators only). Status appears below the button:
- Completed without Errors (green) - No corruption detected. Hardware is sound.
- Failed (red) - Errors were reported. The Error Details block shows the raw output — the first error line names the failing subsystem (CPU, memory, or I/O).
- Interrupted (yellow) - Killed by an update, reboot, or signal. Re-run it.
A failed stress test almost always means a hardware fault, not a software bug or "too many cameras". Common causes:
- Faulty RAM - the most common cause of memory or random CPU errors. Run an overnight memory test (e.g.
memtest86) to confirm and replace any failing module. - Unstable or undersized power supply - undervolting causes CPU compute errors under load. On Raspberry Pi, use the official 27W USB-C adapter; on mini PCs, replace the brick or PSU.
- Overheating and thermal throttling - a CPU that throttles or errors as it heats up will fail the test. See Overheating.
- Failing storage or USB enclosure - I/O errors on the drive or a flaky USB-to-SATA bridge cause storage failures. Check SMART on the Storage tab and try a different cable/enclosure.
- Marginal silicon on overclocked or custom builds - rare, but self-built units with aggressive BIOS settings can fail compute checks. Reset BIOS to defaults.
Tip: A passing stress test confirms the hardware is not corrupting data. It does not confirm the unit has enough CPU for your camera count — that is a separate question, see High CPU and Load below and Hardware Specifications.
If the test fails repeatedly on a unit purchased from TetherX, contact us with the error details and serial number. On custom-built units, the fault is almost always in the RAM, PSU, drive, or cooling — replace components and re-run.
Performance Issues
The Performance & Network section shows resource usage. Thresholds:
| Metric | Normal | Warning | Critical |
|---|---|---|---|
| CPU | Under 80% | 80-90% | Above 90% |
| Memory | Under 80% | 80-90% | Above 90% |
| Load | Under 4.0 | 4.0-8.0 | Above 8.0 |
| IO Wait | Under 15% | 15-20% | Above 20% |
| CPU Temp | Under 70°C | 70-79°C | Above 79°C |
| HDD Temp | Under 50°C | 50-54°C | 55°C and above |
| SSD Temp | Under 60°C | 60-69°C | 70°C and above |
| NVMe Temp | Under 70°C | 70-79°C | 80°C and above |
Warning: Sustained warnings on these metrics cause recording gaps, dropped frames, delayed event uploads, and slow web interface response. Investigate any red or yellow indicator.
High CPU and Load
CPU % measures instantaneous processor utilisation. Load measures the average number of processes waiting to run over the last minute — on a 4-core system, a load of 4.0 means every core is fully busy.
Symptoms: Choppy live view, missed events, slow page loads, delayed snapshot uploads, recordings cutting out.
Causes and fixes:
- Too many cameras for the CPU - the most common cause. Look up your CPU's GeekBench 6 Multi-Core score and divide by 150 — that is your approximate 4K camera capacity. See CPU Recommendations.
- Analytics stream too high - a high-resolution or H.264 High profile analytics stream adds 30-50% CPU per camera. Reconfigure cameras to a 720p @ 5fps H.264 Baseline secondary stream. See Camera Setup.
- Recording resolution or bitrate too high - reduce primary stream bitrate or frame rate on the camera.
- TetherX AI on a unit without an AI accelerator - AI analytics on CPU alone is expensive. See TetherX AI and Hardware Specifications#Graphics / GPU.
- Undersized custom build - cross-check the unit against Hardware Specifications for your deployment size.
Tip: Load consistently above your CPU's core count (e.g. load 8 on a 4-core CPU) means the unit cannot keep up — reduce camera count or upgrade hardware. Brief spikes during reboot or update are normal.
IO Wait and Drive Load
IO Wait is the percentage of time the CPU spent idle waiting for storage. High IO wait means the drive cannot keep up with recording writes.
Symptoms: Recording gaps despite low CPU, growing event upload queue, very slow page loads when browsing recordings, drive temperature climbing.
Causes and fixes:
- Unsuitable drive - SMR (Shingled Magnetic Recording) hard drives, low-quality USB sticks, and SD cards cannot sustain continuous-write loads. Use CMR HDDs or a quality SSD. See Storage Hardware Recommendations.
- Failing or worn drive - check Drive Health and SMART data on the Storage tab. See Drive Issues.
- USB enclosure or cable - cheap USB-to-SATA adapters drop into PIO mode or disconnect under load. Swap the enclosure or cable; prefer direct SATA or NVMe.
- Drive almost full - approaching capacity slows writes on most filesystems. Confirm rotation is working on the Storage tab.
- Too many cameras for a single drive - high camera counts need NVMe or RAID. See Storage Hardware Recommendations.
Tip: Open the Storage tab and check write speed and queue depth. Write speed far below the drive's rated spec means the drive, cable, or enclosure is the bottleneck — not TetherBox software.
Overheating
High temperatures cause thermal throttling — the CPU automatically slows itself down to avoid damage, producing recording gaps, frame drops, and stress test failures. Sustained high HDD/SSD temperature shortens drive life and can cause data corruption.
Symptoms: Performance drops in warm rooms or during summer, stress test failing intermittently, unit randomly rebooting, CPU temperature in warning or critical range on the status page.
Causes and fixes:
- Inadequate airflow - move the unit out of enclosed cabinets, away from walls, off carpet. Leave at least 10 cm clearance on all vented sides.
- Direct sunlight or hot rooms - relocate the unit. Ambient room temperature above 30°C is hard on any fanless or compact PC.
- Dust-blocked vents or fans - open the case and clear dust with compressed air. Check fan blades spin freely.
- Dried thermal paste - on units more than 3-4 years old, replace CPU thermal paste.
- Undersized cooling for the workload - fanless mini PCs and Raspberry Pi units have limited thermal headroom. If the CPU runs at 80-100% continuously, the unit needs active cooling or a more capable CPU. See Hardware Specifications.
- HDD running hot - HDDs above 50°C lose lifespan rapidly. Improve ventilation or move to an SSD. See Storage Hardware Recommendations.
Tip: Watch the CPU Temp value while the unit is under typical load. If it climbs steadily until it hits critical, then drops as cameras start disconnecting, you have a cooling problem — not a network problem.
For any performance issue on a self-built unit, verify hardware against Hardware Specifications before assuming a software fault.
Network Issues
The Network indicator shows latency and packet loss between the TetherBox and TetherX servers:
- Green - Excellent connection (low latency, no packet loss)
- Yellow - Degraded connection affecting video streaming
- Red - Severe issues causing buffering, delays, or disconnections
The Network Information section shows:
- External IP address
- Gateway address
- Internet speed (run a speed test)
- LAN interface speeds and IP addresses
Tip: LAN speeds below 1000 Mbps show in red. Gigabit networking is recommended for multiple cameras.
State Issues
If your TetherBox is stuck in a particular state (Starting, Updating, Restarting), see TetherBox States for expected durations and troubleshooting steps.
Camera Issues
For cameras not recording, showing offline, or displaying incorrectly, see Camera Troubleshooting. Camera issues are often caused by:
- Network connectivity between TetherBox and camera
- Camera authentication failures
- Incorrect stream configuration
Still Need Help?
If the status page doesn't reveal the issue:
- Check the Reboots tab for recent restart patterns
- Check the Connections tab for connection history
- Note any error messages or unusual readings
- Contact us with the TetherBox serial number and screenshots of the status page
Referenced in:
- Local Streaming
- Changing DNS Settings on Your Device
- Health Dashboard
- Getting Started for Integrators
- Troubleshooting Kit
- CPU Recommendations
- Connecting your TetherBox to the Internet
- Emergency Console Login
- How TetherBox Detects Devices
- Power Recovery & BIOS Settings
- Remote Power Management
- Setting a Static IP Address on your TetherBox
- Storage Hardware Recommendations
- TetherBox