Troubleshooting

This guide covers the most common issues you may encounter with your PCS and how to resolve them.

App Won't Start

Symptoms: An app shows as "Down" in the admin panel, or you see an error when visiting its URL.

Steps to diagnose:

1. Go to Admin Panel → Apps and check if the app shows any issues.
2. Go to Admin Panel → Terminal, click Connect, and run:

   docker ps -a | grep <app-name>

   This shows whether the container exited and its exit code.
3. Check the app's logs:

   docker logs <container-name> --tail 100

Common causes and fixes:

Cause	Fix
Port conflict	Another container is using the same port. Stop the conflicting container or change the port.
Out of memory	Check Resources → CPU tab for memory usage. Stop unused apps to free RAM.
Corrupted data	Restore from a backup via Apps page, or remove and reinstall the app.
Docker image pull failed	Check internet connectivity. Run docker pull <image> manually from the Terminal.

---

Domain Not Accessible

Symptoms: Visiting yourdomain.nsl.sh shows a connection error or timeout.

Steps to diagnose:

1. Check if the PCS is reachable at all using the sslip.io fallback domain (e.g. 169-58-42-143.sslip.io).
2. Go to Admin Panel → Domain and verify the public IP matches your actual IP.
3. Check Admin Panel → Health and click Run now to trigger a self-check.

Common causes and fixes:

Cause	Fix
IP address changed	Your ISP assigned a new IP. Run a self-check from Health page — it will detect the new IP and update routing.
Caddy (web server) is down	From Terminal: docker ps | grep caddy. If it's not running: sudo systemctl restart caddy or run a self-check.
ISP blocking port 443	Some ISPs block inbound HTTPS. Contact your ISP or consider using Cloudflare proxy (see Domain page).
DNS propagation delay	If you recently changed your domain settings, wait up to 24 hours for DNS to propagate.

---

Certificate Errors

Symptoms: Browser shows "Your connection is not private" or a certificate warning.

Steps to diagnose:

1. Go to Admin Panel → Certificates and click Refresh.
2. Check if the affected domain shows "Let's Encrypt" or "Internal CA".

Common causes and fixes:

Cause	Fix
Internal CA certificate	Caddy couldn't get a Let's Encrypt certificate. Check that port 443 is open and accessible from the internet.
Rate limit exceeded	Let's Encrypt has rate limits. Wait a few hours and the certificate will be automatically retried.
Certificate expired	Run a self-check from Health → Run now. The nightly maintenance should have renewed it, but a manual run will force renewal.
Custom domain without Cloudflare	If using direct DNS without Cloudflare, you need to configure certificates yourself. Consider switching to Cloudflare (recommended).

tip

Gateway routes (.nsl.sh domains) and .nip.io routes intentionally use Yundera's internal CA. This is by design. Only .sslip.io domains use Let's Encrypt.

---

SSO Login Issues

Symptoms: Can't log in to the admin panel or apps, SSO page shows errors.

Steps to diagnose:

1. Try accessing the CasaOS dashboard directly at https://casaos-yourdomain.nsl.sh/.
2. If CasaOS works, the issue is with the Dex authentication service.
3. From Terminal, check Dex logs:

   docker logs dex --tail 50

Common causes and fixes:

Cause	Fix
Wrong password	Use the credentials shown in System Information → Default User.
Dex service down	Run a self-check from Health → Run now to restart all system services.
Browser cookies	Clear your browser cookies for the .nsl.sh domain and try again.
Clock skew	If the PCS clock is significantly off, SSO tokens may be rejected. Reboot the host from System Information → Reboot host.

---

Slow Performance

Symptoms: Apps are slow to respond, pages take a long time to load.

Steps to diagnose:

1. Go to Admin Panel → Resources.
2. Check the CPU tab: is load average above the number of cores?
3. Check Memory: is swap heavily used?
4. Check Disk tab: is the root filesystem above 90%?

Common causes and fixes:

Cause	Fix
CPU overload	Check top processes. Stop unused apps from the Apps page.
RAM exhaustion	Swap usage indicates RAM shortage. Stop memory-heavy apps or upgrade to a PCS with more RAM.
Disk full	Clean up old backups from Apps page, or remove unused app data. From Terminal: docker system prune to clean unused Docker resources.
Network bottleneck	Run a speed test from Resources → Network tab to check bandwidth.
Slow disk I/O	Run a disk benchmark from Resources → Disk tab. If results are much lower than expected, the disk may be failing.

---

App Data Lost

Symptoms: An app's data has disappeared or been corrupted.

Steps to diagnose:

1. Go to Admin Panel → Apps and check if backups exist for the app.
2. From Terminal, check if the data directory exists:

   ls -la /DATA/AppData/<app-name>/

Recovery options:

1. Restore from backup — If backups exist, use the Restore button on the Apps page.
2. Check Docker volumes — Some data might be in Docker volumes rather than /DATA/AppData.
3. Reinstall the app — If data is truly lost and no backup exists, reinstall through CasaOS.

tip

Always create regular backups from the Apps page before making changes. Prevention is the best cure.

---

Self-Check / Update Failed

Symptoms: The nightly maintenance shows errors in the Health log.

Steps to diagnose:

1. Go to Admin Panel → Health and check the Log tail.
2. Look for error messages in red or lines containing "ERROR" or "FAILED".

Common causes and fixes:

Cause	Fix
No internet connection	Check network connectivity from Terminal: ping 8.8.8.8.
Docker registry unavailable	Temporary issue with the container registry. The next nightly run will retry.
Disk full	Docker can't pull new images. Free up disk space first.
Wrong update channel	If you changed to a non-stable channel, switch back to Stable from Health page.

---

Still Need Help?

If none of the above solutions work:

1. Go to Admin Panel → Support.
2. Enable Attach yundera.log and Grant SSH access.
3. Describe your issue in detail and click Send to support.

The Yundera support team will be able to diagnose the issue directly on your PCS.