Troubleshooting
Common issues and step-by-step solutions to get your device working.
Common Issues
Device not powering on
Diagnose and fix power-related issues.
Check the power adapter
Ensure you're using a USB-C PD adapter with 45-65W output. The included 65W adapter is recommended. Check that the adapter is properly connected to both the outlet and device.
Verify the power source
Try a different power outlet. If using a power strip or surge protector, try connecting directly to a wall outlet. Some power strips may not provide sufficient power delivery.
Check the USB-C cable
If using a third-party adapter, ensure the USB-C cable supports PD and data transfer. Some cables are charge-only and won't work. The included cable is rated for 100W PD.
LED indicators
If no LED lights up, there may be a hardware issue. If the LED flashes red rapidly, this indicates a power delivery problem. Contact support if issues persist.
Factory reset
As a last resort, perform a factory reset by holding the reset button for 10 seconds while powering on. This will reset all settings but won't delete downloaded models.
Network connectivity problems
Resolve Ethernet and Wi-Fi connection issues.
Ethernet not connecting
Check cable connections at both ends. Try a different Ethernet port on your router. The device LED should show blue activity when network traffic occurs.
Device not found on network
Ensure device and computer are on the same network. Try accessing via IP instead of thox.local. Check your router's DHCP client list for the device.
Wi-Fi connection drops
Move the device closer to your router. Check for interference from other 2.4GHz devices. Consider using 5GHz if available. Update to the latest firmware.
Slow network performance
Ethernet is recommended for best performance. If using Wi-Fi, ensure strong signal (check with: thox network status). Avoid placing the device near metal objects or walls.
DNS resolution issues
If thox.local doesn't resolve, your network may not support mDNS. Use the IP address directly or configure your router's DNS settings.
Slow or unresponsive performance
Optimize device performance and responsiveness.
Check system resources
Run "thox status" or check the web dashboard. High memory usage (>90%) or CPU throttling indicates resource constraints.
Model too large
Larger models (13B+) require more resources. Try a smaller model variant. Use "thox models list" to see model sizes and "thox models switch [name]" to change.
Clear cache
Clear the inference cache: "thox cache clear". This frees memory but may slightly slow first responses to repeated queries.
Restart the service
Restart the Thox service: "thox service restart". This clears any memory leaks and resets the inference engine.
Check for updates
Newer firmware often includes performance improvements. Run "thox update check" and "thox update install" to get the latest version.
Device running hot or thermal throttling
Manage thermal performance and cooling.
Check ventilation
Ensure at least 2 inches of clearance on all sides. Remove any objects blocking the vents. Don't place in enclosed spaces or on soft surfaces like carpet.
Ambient temperature
The device operates best at 0-35°C (32-95°F). In warmer environments, performance may be reduced. Consider air conditioning or a small fan.
Workload management
Continuous heavy inference can cause thermal buildup. The device will automatically throttle to prevent damage. Consider smaller models or batching requests.
Check thermal status
Run "thox thermal status" to see current temperatures and throttle state. Sustained operation above 80°C may trigger protective throttling.
Cleaning
Dust buildup can reduce cooling efficiency. Periodically use compressed air to clean the vents. Do not open the enclosure; this voids the warranty.
Storage and model download issues
Fix storage space and download problems.
Check available space
Run "thox storage status" to see available space. Large models (7B+) require 4-15GB each. Delete unused models with "thox models delete [name]".
Download fails or stalls
Check network connection. Large models take time; a 7B model takes 10-20 minutes on typical connections. Use "thox models pull [name] --resume" to resume failed downloads.
Corrupt model files
If a model fails to load, it may be corrupt. Delete and re-download: "thox models delete [name]" then "thox models pull [name]".
External storage
Connect a USB drive for additional storage. Format as ext4 and mount: "thox storage mount /dev/sda1". Configure as model storage in /admin/storage.
Common error codes and meanings
Understand and resolve error messages.
E001: Memory allocation failed
The model requires more memory than available. Switch to a smaller model or restart the device to free memory.
E002: Model not found
The requested model isn't installed. List available models with "thox models list" and download with "thox models pull [name]".
E003: Network timeout
Request to the device timed out. Check network connection. Increase timeout in IDE settings or API client configuration.
E004: Authentication failed
Invalid API key or credentials. Regenerate your API key in /admin/api-keys and update your client configuration.
E005: Rate limit exceeded
Too many requests in a short period. Default limit is 60 requests/minute. Adjust in /admin/settings or add delays between requests.
Still having issues?
Our support team is here to help with any problems not covered here.
Submit a Support Ticket