Skip to main content

​
Installation Issues

Symptoms: docker ps shows no running containersSolutions:
  1. Check Docker is running: 
    sudo systemctl status docker  # Linux
# or check Docker Desktop is running on macOS
  2. View container logs: 
    docker logs nolongerevil-server
  3. Check for port conflicts: 
    sudo lsof -i :8000  # Check if port 8000 is in use
sudo lsof -i :8082  # Check if port 8082 is in use
  4. Restart Docker: 
    sudo systemctl restart docker  # Linux
# or restart Docker Desktop on macOS
Ubuntu/Debian:
sudo apt-get update
sudo apt-get install --fix-missing build-essential libusb-1.0-0-dev gcc pkg-config
macOS:
# Make sure Homebrew is up to date
brew update
brew doctor
brew install libusb pkg-config

​
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: 
    sudo ./NoLongerEvil-*.AppImage
  2. Add udev rules for a permanent fix: 
    echo 'SUBSYSTEM=="usb", ATTR{idVendor}=="0451", MODE="0666"' | sudo tee /etc/udev/rules.d/99-omap.rules
sudo udevadm control --reload-rules
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: 
    docker ps | grep nolongerevil
curl http://localhost:8082/health  # Should respond
  2. Firewall allows connections: 
    sudo ufw allow 8000  # Linux
sudo ufw allow 8082
  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): 
    nslookup your-domain.com
  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:
http://[THERMOSTAT-IP]:8080/cgi-bin/api/settings
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:
http://[SERVER-IP]:[PORT]/info
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: 
ssh root@[THERMOSTAT-IP]   # default password: nolongerevil
cat /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):
ssh root@[THERMOSTAT-IP]
# Default password: nolongerevil
vi /etc/nestlabs/client.config
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:
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:
sudo apt-get install certbot
sudo certbot certonly --standalone -d your-domain.com
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:
docker logs nolongerevil-server
Common causes:
  • Port already in use
  • Missing environment variables
  • Insufficient resources (RAM/CPU)
  • Database connection failed
Check resource usage:
docker stats
Check port mappings:
docker ps
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:
docker run -p 8000:8000 -p 8082:8082 ...
Check Docker disk usage:
docker system df
Clean up unused resources:
docker system prune -a
docker volume prune
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: 
    sudo ufw status
sudo ufw allow 8000
sudo ufw allow 8082
  3. Public IP correct: 
    curl ifconfig.me  # Shows your public IP
  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:
sudo certbot certificates
Renew if expired:
sudo certbot renew
Test HTTPS endpoint:
curl -k https://your-domain.com  # -k skips cert validation
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:
top
docker stats
df -h  # Check disk space
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:
docker stats
Restart container to free memory:
docker restart nolongerevil-server

​
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:
docker logs nolongerevil-server

Hosted Service

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