Skip to main content

​
Installation Issues

Symptoms: docker ps shows no running containersSolutions:
  1. Check Docker is running:
  2. View container logs:
  3. Check for port conflicts:
  4. Restart Docker:
Ubuntu/Debian:
macOS:

​
Thermostat Flashing Issues

Try these steps in order:
  1. Back plate sequence first — Attach to wall mount, wait 2–3 seconds, then remove. The back plate contact arms DFU mode.
  2. Connect USB immediately after removing from back plate — Use a data-capable cable (not charge-only)
  3. Charge battery — Ensure >50% battery
  4. Reboot — Hold display for 10-15 seconds
See DFU Mode Troubleshooting for more details
Common issues:
  • Contacts not held long enough - Keep bridging until USB connects
  • Wrong contacts bridged - Double-check the image in the guide
  • Battery disconnected - Device won’t boot without battery
  • Screen still on - Make sure screen is off before bridging
Solution: Try multiple times, ensuring:
  • Battery is connected
  • Screen is off
  • Installer is waiting
  • Bridge contacts, THEN connect USB while holding bridge
Linux:
  1. Check USB permissions — run the installer app with sudo:
  2. Add udev rules for a permanent fix:
macOS:
  • Grant USB permissions in System Preferences → Security & Privacy
Both:
  • Try different USB cable (must be data-capable)
  • Try different USB port
Back plate sequence reminder: Attach to back plate (2–3 sec) → remove → plug USB. This must be repeated for each flash attempt. If you plugged USB without the back plate step, the device booted normally instead of entering DFU mode.

​
Server Connection Issues

The NLE server is a standalone service, separate from the firmware flashing tool. It runs as a Docker container using the image ghcr.io/codykociemba/nolongerevil-selfhosted:latest, as a Python service, or as a Home Assistant add-on. See the self-hosted installation guide for server setup instructions.
Home Assistant Add-on users: The add-on’s external device port is 9543 (not 8000). The thermostat must be configured to reach http://[HA-IP]:9543.If your thermostat isn’t connecting: verify api_origin in the add-on’s Configuration tab is set to an IP address, not homeassistant.local.The control dashboard (port 8082) is only accessible via the HA sidebar (Ingress) by default. To expose it directly, go to Settings → Add-ons → No Longer Evil → Configuration → Network and assign a host port to container port 8082.
Check:
  1. API server is running:
  2. Firewall allows connections:
  3. Port forwarding configured (if remote access):
    • Check router settings
    • Verify ports 8000 and 8082 are forwarded to your server
  4. DNS resolves correctly (if using domain):
  5. Thermostat can reach server:
    • Check WiFi connection on thermostat
    • Verify thermostat is on same network (for local-only setup)
Symptoms: Thermostat shows No Longer Evil firmware but connects to cloud, or shows “No Server”Method 1 — NLEAPI (easier, web-based):The thermostat exposes a configuration API at port 8080. Navigate to:
Find cloudregisterurl in the settings and update it to your server’s /entry endpoint:
  • Standalone Docker: http://[SERVER-IP]:8000/entry
  • HA Add-on: http://[HA-IP]:9543/entry
You can find the exact URL by querying your server’s info endpoint:
Password protection: If the thermostat has been powered on for more than 30 minutes, the NLEAPI is protected by a password. To find the password, SSH into the thermostat and read /etc/nestlabs/apikey.txt:
Use this value as the password when the NLEAPI prompts for authentication.
After saving, reboot the thermostat.
Method 2 — SSH / direct file edit (fallback):
Find the cloudregisterurl entry and update the value to your server’s /entry endpoint (same values as Method 1 above).Save with :wq, then reboot:
After reboot: Settings (gear icon) → Nest App → Get Entry Key (only needed if REQUIRE_DEVICE_PAIRING=true).
Self-signed certificates: If using self-signed certs, browsers will warn. You can:
  • Use Let’s Encrypt for free valid certificates
  • Accept the browser warning (not recommended for production)
Let’s Encrypt setup:
Then configure CERT_DIR in your Docker environment to point to the certificates in /etc/letsencrypt/live/your-domain.com/

​
Docker Issues

View logs to see why:
Common causes:
  • Port already in use
  • Missing environment variables
  • Insufficient resources (RAM/CPU)
  • Database connection failed
Check resource usage:
Check port mappings:
Look for 0.0.0.0:8000->8000/tcp and 0.0.0.0:8082->8082/tcpIf ports aren’t mapped, recreate containers with proper port mapping:
Check Docker disk usage:
Clean up unused resources:
Warning: This will remove all stopped containers and unused images

​
Network & Remote Access

Check these in order:
  1. Port forwarding configured:
    • Log into your router
    • Forward ports 8000, 8082 to your server’s local IP
    • Verify forwards are active
  2. Firewall allows traffic:
  3. Public IP correct:
  4. Dynamic DNS working (if using DDNS):
    • Verify DNS record points to current IP
    • Check DDNS client is running and updating
  5. ISP not blocking ports:
    • Some ISPs block common ports
    • Try alternative ports or contact ISP
Check certificate:
Renew if expired:
Test HTTPS endpoint:
Common issues:
  • Certificate not installed correctly
  • Server not configured for HTTPS (CERT_DIR env var not set)
  • Port 8000 not open
  • Domain doesn’t match certificate

​
Performance Issues

Check resource usage:
Solutions:
  • Allocate more resources to Docker
  • Enable DEBUG_LOGGING=false to reduce log overhead
  • Use faster storage (SSD vs HDD)
Check which container is using memory:
Restart container to free memory:

​
Still Having Issues?

Join Discord

Ask the self-hosting community for help

GitHub Issues

Report bugs or check existing issues

Check Logs

Always check Docker logs first:

Hosted Service

Consider using the hosted service if self-hosting is too complex