Troubleshooting HellaNZB Remote: Common Issues and FixesHellaNZB Remote is a convenient web-based interface for controlling NZB downloaders and managing Usenet activity from anywhere. Like any software that relies on multiple components (web interface, downloader backend, network, and remote access), users can encounter various issues. This article covers common problems, step-by-step diagnostics, and practical fixes so you can restore reliable remote control quickly.
1. Common symptom categories and first steps
Before diving into specific problems, run these quick checks:
- Confirm the HellaNZB Remote web UI loads in your browser. If it doesn’t, note any error messages or HTTP status codes.
- Verify the downloader backend (e.g., SABnzbd, NZBGet) is running locally and reachable from the machine hosting HellaNZB Remote.
- Ensure network connectivity between your client (phone/remote browser), the HellaNZB Remote host, and the downloader host.
- Check logs: HellaNZB Remote logs, and the downloader’s logs (SABnzbd or NZBGet).
- Note whether the issue occurs locally (same LAN) or only when accessing remotely (over the internet). This distinction narrows down network/port/router/NAT/firewall causes.
If you haven’t already, restart the HellaNZB Remote service and the downloader. Many transient problems clear with a restart.
2. Unable to reach HellaNZB Remote web UI
Symptoms: Browser times out, “connection refused,” or shows a generic network error.
Causes and fixes:
- Service not running: On the host, check the HellaNZB Remote process/service status and restart it. Example commands (adjust for your OS and how you installed it):
- systemd: sudo systemctl status hellanzb-remote && sudo systemctl restart hellanzb-remote
- Docker: docker ps → docker restart
- Port binding issue: Confirm HellaNZB Remote listens on the configured port (default varies). Use:
- Linux: sudo ss -tlnp | grep
or sudo netstat -tlnp | grep
- Linux: sudo ss -tlnp | grep
- Firewall blocking: Ensure local firewall (ufw, firewalld, iptables) allows incoming connections on the HellaNZB Remote port.
- Example: sudo ufw allow
/tcp
- Example: sudo ufw allow
- DNS or URL issues: If you use a hostname, verify DNS resolves to the correct IP (dig or nslookup). Try direct IP in browser.
- Browser caching or HTTPS mismatch: Clear cache or try private mode. If HellaNZB Remote is configured for HTTP but you access via HTTPS (or vice versa), correct the URL or enable proper TLS.
3. HellaNZB Remote loads but shows empty data or connection errors to backend
Symptoms: Web UI loads but shows no queue, “cannot reach SABnzbd/NZBGet,” or authentication errors.
Causes and fixes:
- Backend service down: Ensure SABnzbd/NZBGet is running. Restart if needed.
- Incorrect backend URL/API key: Check HellaNZB Remote configuration — the downloader URL, port, API key, and whether it expects HTTP or HTTPS must match the downloader’s settings.
- Test API access directly: for SABnzbd, try http://
: /api?mode=queue&output=json&apikey=
- Test API access directly: for SABnzbd, try http://
- CORS or cross-origin requests blocked: If the UI is served from a different origin than the downloader API, ensure the downloader allows requests from HellaNZB Remote host or enable proxying through HellaNZB Remote.
- TLS/HTTPS issues: If the downloader uses self-signed certificates, HellaNZB Remote may reject the connection. Use a valid cert or configure HellaNZB Remote to ignore certificate verification only if you understand the security implications.
- Version incompatibility: Verify that your HellaNZB Remote version supports the downloader version. Update HellaNZB Remote or the downloader if incompatibilities are known.
4. Authentication and permission problems
Symptoms: “Invalid API key,” repeated login prompts, or limited functionality when authenticated.
Causes and fixes:
- Wrong API key: Regenerate or copy the API key from the downloader and paste into HellaNZB Remote config exactly.
- IP restrictions on downloader: Some services can restrict API usage to certain IPs. Allow the HellaNZB Remote host IP in downloader settings.
- HellaNZB Remote user permissions: Confirm the HellaNZB Remote account has correct privileges if the UI supports multiple users/roles.
- Reverse proxy auth interference: If using Nginx/Traefik with HTTP auth or OAuth, ensure HellaNZB Remote’s endpoints are passed through correctly and session cookies aren’t stripped.
5. Remote access works on LAN but not over the Internet
Symptoms: Accessible from devices on the same network, but remote access fails.
Causes and fixes:
- Router port forwarding/NAT not configured: Forward the external port to the HellaNZB Remote host internal IP and port. Use a static local IP or DHCP reservation to avoid forwarding breakage.
- ISP blocks or CGNAT: Some ISPs block incoming ports or use Carrier-Grade NAT (CGNAT), preventing direct inbound connections. Workarounds:
- Use a VPN to a home network.
- Use a reverse SSH tunnel to a remote VPS.
- Use a remote tunneling service (e.g., Cloudflare Tunnel, Tailscale, or ngrok) to expose the web UI securely.
- Dynamic IP: If your home IP changes, use a dynamic DNS (DDNS) service to keep a consistent hostname.
- Firewall rules on router: Ensure the router’s firewall allows the forwarded port and that any “remote access” toggle is enabled.
Security note: If exposing HellaNZB Remote to the internet, secure it with HTTPS and strong authentication. Limit access by IP where possible and consider putting it behind a VPN or reverse proxy with additional auth.
6. Downloads not starting or stalled after adding NZBs remotely
Symptoms: NZB accepted by UI but never starts in SABnzbd/NZBGet or stays in queue indefinitely.
Causes and fixes:
- Queue or category misconfiguration: HellaNZB Remote may send NZBs with an expected category or folder that the downloader doesn’t recognize. Verify default categories match.
- Permissions on download folders: Ensure the downloader has write permission where it writes temporary and completed files.
- Check user ownership and filesystem permissions for both the temporary and final download directories.
- Post-processing scripts failing: If post-processing (parsing, extraction, or movers) fails, downloads might appear stuck. Check downloader logs for script errors and fix paths/permissions.
- Disk space: Low disk space on temporary or final volume can prevent downloads. Free up space or expand the storage.
- Par2 repair/unpack issues: Missing or corrupted par2 or unrar binaries can cause unpack failures. Install required tools on the downloader host.
7. Performance issues: slow UI, delayed updates
Symptoms: UI responds slowly, queue updates lag, or actions take a long time.
Causes and fixes:
- Resource limits on host: Check CPU, memory, and disk I/O on the HellaNZB Remote host. Upgrade resources or move to a faster system if overloaded.
- Excessive polling interval: HellaNZB Remote polls the backend periodically. If polling is too frequent or backend is slow to respond, increase intervals or use websocket/push support if available.
- Network latency: High latency between HellaNZB Remote and downloader (e.g., when they run on different networks) will slow updates. Co-locate services or use a faster connection.
- Database growth or corruption: If HellaNZB Remote stores history or state in a local DB that has grown large, compact or clean old entries. Back up then vacuum/optimize DB if supported.
8. Errors shown in logs — how to interpret and act
What to collect:
- HellaNZB Remote log entries (timestamped around the problem).
- Downloader logs (SABnzbd/NZBGet) for the same times.
- Browser console logs for JS errors (press F12 → Console).
- Network traces if needed (curl or wget test commands, or browser Network tab).
Common log error patterns and responses:
- Connection refused / timeout → network, port, or service down.
- 401 / 403 HTTP errors → authentication or permission issues.
- SSL certificate errors → misconfigured TLS or self-signed certs.
- JSON parse or API schema errors → version mismatch or invalid API response.
Action: match the error to the likely cause list above, implement the suggested fix, then reproduce the action to confirm resolution.
9. Backup and recovery best practices
- Keep a backup of HellaNZB Remote configuration (API keys, backend URLs, user settings).
- Periodically export or snapshot any local database or settings files.
- Maintain backups of downloader configuration, categories, and post-processing scripts.
- Use version control or at least store config backups off-host (encrypted) so you can quickly restore after failures.
10. When to seek help / provide details to support
If you need help from forums or the HellaNZB Remote project:
- Provide HellaNZB Remote version, downloader type and version (SABnzbd/NZBGet), OS and version, and whether it’s Docker/containerized.
- Include exact log excerpts (timestamped) and the steps you took just before the issue.
- Note whether the issue is local-only or remote-only and whether firewall/port forwarding is in use.
Summary checklist (quick troubleshooting flow)
- Restart HellaNZB Remote and downloader.
- Confirm HellaNZB Remote UI loads locally and resolves DNS.
- Verify backend URL, port, and API key.
- Check firewall/router port forwarding and ISP/CGNAT issues for remote access.
- Inspect downloader logs for post-processing, permission, or disk issues.
- Securely expose the UI (HTTPS + auth) or use a VPN/tunnel if needed.
If you want, tell me the specific error messages, logs, or your setup (downloader, OS, network) and I’ll give targeted steps.
Leave a Reply