Troubleshooting

Troubleshooting

🇫🇷 Cette page est également disponible en français : fr-Troubleshooting

This page covers the most common issues encountered with a Nextcloud Azure Marketplace deployment, along with diagnostic commands and solutions.

---

Prerequisites

• You are connected to the VM via SSH — see SSH-Connection.
• All four services are expected to be running: Nginx, PHP-FPM 8.3, PostgreSQL 16, Redis.

---

Issue 1 — Port 443 Is Blocked (Cannot Access Nextcloud via HTTPS)

Symptoms: Browser shows "connection refused" or times out on https://cloud.example.com.

Diagnosis:

# Check if Nginx is listening on 443
sudo ss -tlnp | grep ':443'

# Check NSG / firewall rules (verify from Azure Portal)
# Settings > Networking > Inbound port rules — port 443 must be allowed

Solutions:

1. Verify that the NSG (Network Security Group) for the VM has an inbound rule allowing TCP port 443. Go to the Azure Portal > VM > Networking > Inbound port rules.
2. Verify Nginx is running: sudo systemctl status nginx
3. Restart Nginx if needed: sudo systemctl restart nginx

---

Issue 2 — TLS Certificate Expired

Symptoms: Browser shows security warning "Your connection is not private" (ERR_CERT_DATE_INVALID).

Diagnosis:

# Check certificate expiry date
sudo certbot certificates

Solution:

Renew the certificate manually:

sudo certbot renew
sudo systemctl reload nginx

For automatic renewal, verify that the certbot timer is active:

sudo systemctl status certbot.timer

If the timer is inactive, enable it:

sudo systemctl enable --now certbot.timer

---

Issue 3 — Database Connection Lost

Symptoms: Nextcloud shows "Error while trying to create admin user: Failed to connect to the database" or "could not connect to server: Connection refused".

Diagnosis:

sudo systemctl status postgresql
sudo journalctl -u postgresql --since "1 hour ago" | tail -30

Solutions:

1. Start or restart PostgreSQL: sudo systemctl restart postgresql
2. Check disk space — PostgreSQL can fail if the disk is full:

   df -h /

3. Check PostgreSQL log: sudo journalctl -u postgresql --since "1 hour ago" | tail -50

---

Issue 4 — PHP-FPM Crash (502 Bad Gateway)

Symptoms: Nginx returns a 502 Bad Gateway error. Pages do not load.

Diagnosis:

sudo systemctl status php8.3-fpm
sudo journalctl -u php8.3-fpm --since "30 minutes ago" | tail -20

Solutions:

1. Restart PHP-FPM: sudo systemctl restart php8.3-fpm
2. Check PHP error log: sudo tail -50 /var/log/php8.3-fpm.log
3. Increase memory limit if processes are killed by OOM (Out of Memory): Edit /etc/php/8.3/fpm/php.ini → memory_limit = 512M, then restart PHP-FPM.

---

Issue 5 — Redis Unavailable (Locking Issues)

Symptoms: Nextcloud shows "Could not obtain lock" errors, or file operations fail with locking warnings.

Diagnosis:

sudo systemctl status redis-server
redis-cli ping

Expected response from redis-cli ping: PONG

Solutions:

1. Start or restart Redis: sudo systemctl restart redis-server
2. Check Redis log: sudo tail -30 /var/log/redis/redis-server.log
3. Verify Redis configuration in Nextcloud config.php:

   sudo grep -A 5 'redis' /var/www/nextcloud/config/config.php

---

Issue 6 — "Access through untrusted domain" (HTTP 400 on FQDN)

Symptoms:

• Browser shows: "Access through untrusted domain"
• https://<vm-fqdn>/status.php returns HTTP 400
• Access by IP may still work (https://<vm-ip>/)

Diagnosis:

# Check current trusted domains
sudo -u www-data php /var/www/nextcloud/occ config:system:get trusted_domains

# Confirm status.php behavior on FQDN
curl -k -I https://<vm-fqdn>/status.php

If the FQDN is missing from trusted_domains, Nextcloud rejects the Host header and returns 400.

Immediate fix (running VM):

# Add your FQDN as the next trusted domain index
FQDN="nextcloud-vm.canadacentral.cloudapp.azure.com"
INDEX=$(sudo -u www-data php /var/www/nextcloud/occ config:system:get trusted_domains | wc -l)
sudo -u www-data php /var/www/nextcloud/occ config:system:set trusted_domains "$INDEX" --value="$FQDN"

# Verify
sudo -u www-data php /var/www/nextcloud/occ config:system:get trusted_domains
curl -k -I "https://$FQDN/status.php"

Expected result: status.php returns HTTP 200, and the login page is reachable via FQDN.

Durable fix (new deployments):

When you use DNS, ensure the domain is available during first boot and injected into Nextcloud config:

1. Set NC_DOMAIN=<vm-fqdn> in /etc/nextcloud/config.env before nextcloud-first-boot.service runs.
2. Run first boot and verify trusted_domains includes both IP and FQDN.

This prevents E2E failures such as HTTP 400 on /status.php and login page checks.

---

General Diagnostic Commands

# Check all four services at once
sudo systemctl is-active nginx php8.3-fpm postgresql redis-server

# View Nextcloud application log (last 50 lines)
sudo tail -50 /var/log/nextcloud/nextcloud.log | python3 -m json.tool 2>/dev/null || \
  sudo tail -50 /var/log/nextcloud/nextcloud.log

# Check disk space
df -h

# Check memory usage
free -h

# Check running PHP-FPM workers
ps aux | grep php-fpm | grep -v grep | wc -l

---

Nextcloud Integrity Check

Run the built-in integrity check to detect modified or missing core files:

sudo -u www-data php /var/www/nextcloud/occ integrity:check-core

No output means all core files are intact.

---

Next Steps

Next	Page
Get support	Support
Update Nextcloud	Updating-Nextcloud
Verify services	Post-Deployment-Verification