Fixing CasaOS Login Failures on Set-Top Boxes

Running a home server with CasaOS on a Set-Top Box (STB) can be a fantastic way to manage apps and services, but it’s not without its challenges. Recently, I encountered a frustrating issue: after installing a custom app (in my case, a combination of a web app, database, and Adminer) via CasaOS’s Custom Install menu, I couldn’t log back into the CasaOS web UI. The browser displayed a cryptic error: {“message”: “not found”}. To make matters worse, I also faced a “Network error: Connection refused” when trying to access the server via SSH using PuTTY on port 22. Here’s how I resolved the issue and some tips to prevent it from happening again.

The Problem: CasaOS Login Failure and SSH Connection Issues

After installing a custom app stack (web, database, and Adminer) on my CasaOS server running on an STB with IP 192.168.1.37, the web UI at http://192.168.1.37:80 became inaccessible, showing {“message”: “not found”}. Additionally, attempting to troubleshoot via SSH using PuTTY resulted in a “Connection refused” error on port 22, even though pinging the server worked fine. Since my STB lacks a display or keyboard, I had to rely on network-based solutions or physical reboots.

The root cause? Likely a port conflict (e.g., Adminer or the database trying to use port 80, which CasaOS needs) or a service crash triggered by the custom app installation. Here’s a step-by-step guide to how I fixed it and got my CasaOS server back online.

Step-by-Step Solution

1. Verify Network Connectivity

Since the server was pingable at 192.168.1.37, I confirmed it was online and reachable:

• Open a Command Prompt (Windows) or Terminal (Linux/Mac) and run:

ping 192.168.1.37

• If you see replies (e.g., Reply from 192.168.1.37: bytes=32 time=…), the server is up. If not, check your router’s device list to confirm the server’s IP hasn’t changed (common with DHCP).

2. Physical Reboot of the STB

With no display or keyboard on my STB, I performed a physical reboot:

• Unplug the STB’s power cable, wait 10-15 seconds, and plug it back in.
• Wait 1-2 minutes for the STB to restart.
• Verify the IP is still 192.168.1.37 by pinging again or checking the router’s connected devices.

This reboot resolved my SSH access issue, allowing me to connect via PuTTY to 192.168.1.37 on port 22. If you still get “Connection refused,” proceed to the next steps before attempting another reboot.

3. Fix SSH “Connection Refused” (If Needed)

If SSH still fails after a reboot:

•  Check SSH Service: If you have temporary access to a monitor or another way to log in, check the SSH service:

sudo systemctl status ss

If inactive, enable and start it:

sudo systemctl enable ssh
sudo systemctl start ssh

• Install SSH if Missing: Some minimal CasaOS setups on STBs may not have SSH installed:

sudo apt update
sudo apt install openssh-server -y
sudo systemctl enable ssh
sudo systemctl start ssh

• Check Firewall: Ensure port 22 is open:

sudo ufw allow 22
sudo ufw reload

• Try Alternative Ports: If the STB uses a custom SSH port (e.g., 2222), update the port in PuTTY and retry.

4. Investigate the CasaOS “Not Found” Error

Once SSH access was restored, I logged into the server via PuTTY and checked CasaOS services:

systemctl status casaos-gateway
systemctl status casaos-app-management
systemctl status casaos-user-service
systemctl status casaos

If any service is inactive or failed, restart them:

sudo systemctl restart casaos-gateway
sudo systemctl restart casaos-app-management
sudo systemctl restart casaos-user-service
sudo systemctl restart casaos

Next, check CasaOS logs for clues:

journalctl -u casaos -f

Look for errors like “port already in use” (indicating a port conflict) or “failed to parse compose app” (suggesting a Docker Compose issue from the custom install).

5. Remove Problematic Docker Containers

The custom app installation (Adminer, database, or web app) likely caused a port conflict or service crash. List all Docker containers:

docker ps -a

Identify containers related to your custom app (e.g., adminer, db). Stop and remove them:

docker stop <container-name>
docker rm <container-name>

Restart CasaOS services and check the web UI again at http://192.168.1.37:80.

6. Reset CasaOS User Database (If Login Still Fails)

If the {“message”: “not found”} error persists, the user database may be corrupted. Reset it:

cd /var/lib/casaos/db
sudo mv user.db user.db.backup
sudo systemctl restart casaos-user-service

Access the web UI and create a new user. Back up the user.db file to avoid data loss.

7. Reinstall CasaOS (Last Resort)

If nothing works, back up data in /var/lib/casaos and reinstall CasaOS:

sudo curl -fsSL https://get.casaos.io/uninstall | sudo bash
sudo curl -fsSL https://get.casaos.io | sudo bash

Note: This wipes all apps and settings, so use it sparingly.

Preventing Future Issues

To avoid similar problems when installing custom apps in CasaOS:

• Use Unique Ports: Ensure apps like Adminer or databases don’t conflict with CasaOS’s default port (80). Example Docker Compose for Adminer:

version: '3'
services:
  adminer:
    image: adminer
    restart: always
    ports:
      - 8081:8080

Access Adminer at http://192.168.1.37:8081.

• Install Apps Sequentially: Test each component (web, DB, Adminer) individually to catch conflicts early.
• Set a Static IP: Prevent IP changes by assigning a static IP (e.g., 192.168.1.37) to your STB in your router’s settings.
• Update CasaOS: Keep CasaOS up to date to avoid bugs:

sudo curl -fsSL https://get.casaos.io/update | sudo bash

• Backup Regularly: Save /var/lib/casaos and Docker volumes (docker volume ls) before making changes.

Key Takeaways

The {“message”: “not found”} error in CasaOS often stems from port conflicts or service crashes caused by custom app installations. A simple reboot fixed my SSH access, and removing problematic Docker containers resolved the login issue. For STB users without a display, rely on physical reboots and router checks to maintain network stability. Always use unique ports and back up data to stay safe.

If you’re facing similar issues, let me know in the comments—share your setup (e.g., STB model, installed apps) and any error logs, and I’ll help you troubleshoot further! Check the CasaOS GitHub (IceWhaleTech/CasaOS) or r/CasaOS on Reddit for more community tips.