Troubleshooting Reference

Common issues and solutions for Nextcloud deployments.

Pod Issues

Pods Stuck in Pending

Check:

kubectl describe pod -n nextcloudkup {pod-name}

Common Causes:

  • PVC not bound (check StorageClass)

  • Resource constraints (insufficient CPU/memory)

  • Node affinity/taints preventing scheduling

Pods CrashLoopBackOff

Check logs:

kubectl logs -n nextcloudkup deploy/nextcloud --previous

Common Causes:

  • S3 credentials missing

  • PostgreSQL not ready

  • Config.php corruption

Access Issues

404 Not Found

Symptoms: Site returns 404 error

Checks:

  1. Verify Ingress exists:

    kubectl get ingress -n nextcloudkup

  2. Check for conflicting Ingresses:

    kubectl get ingress -A | grep {domain}

  3. Check Traefik logs:

    kubectl logs -n traefik deployment/traefik | grep nextcloud

Solution: Delete conflicting Ingresses or fix middleware annotations.

503 Service Unavailable

Symptoms: Intermittent 503 errors

Common Causes:

  • Duplicate Ingress resources

  • Pod not ready

  • Service endpoints missing

Checks:

# Check service endpoints
kubectl get endpoints -n nextcloudkup nextcloud

# Check pod readiness
kubectl get pods -n nextcloudkup -l app.kubernetes.io/name=nextcloud

Internal Server Error

Symptoms: Error 500 after login

Common Causes:

  • S3 credentials empty

  • Database connection failed

  • File permissions

Check S3 credentials:

kubectl exec -n nextcloudkup deploy/nextcloud -- \
  php occ config:list system --private | jq '.system.objectstore.arguments'

Should show non-empty key and secret.

Database Issues

Connection Refused

Check PostgreSQL status:

kubectl get cluster -n nextcloudkup nextcloud-postgres
kubectl get pods -n nextcloudkup -l cnpg.io/cluster=nextcloud-postgres

Check pooler:

kubectl get pooler -n nextcloudkup nextcloud-postgres-pooler
kubectl logs -n nextcloudkup deploy/nextcloud-postgres-pooler

Slow Queries

Enable query logging:

kubectl exec -n nextcloudkup nextcloud-postgres-1 -- \
  psql -U postgres -d nextcloud -c "
    ALTER SYSTEM SET log_min_duration_statement = 1000;
    SELECT pg_reload_conf();
  "

Logs queries taking > 1 second.

Storage Issues

Files Not Accessible

Symptom: Users see “File not found” for existing files

Solution: Run file scan

kubectl exec -n nextcloudkup deploy/nextcloud -- \
  php occ files:scan --all

S3 Upload Fails

Check S3 connectivity:

kubectl exec -n nextcloudkup deploy/nextcloud -- \
  curl -I https://fsn1.your-objectstorage.com

Check credentials:

kubectl get secret -n nextcloudkup nextcloud-s3-credentials -o yaml

Disk Space Full

Check pod storage:

kubectl exec -n nextcloudkup deploy/nextcloud -- df -h

Check PVC usage:

kubectl exec -n nextcloudkup nextcloud-postgres-1 -- df -h /var/lib/postgresql

Performance Issues

Slow Response Times

Check resource limits:

kubectl top pods -n nextcloudkup

Increase resources in config.yaml if needed.

Check Redis:

kubectl exec -n nextcloudkup redis-0 -- redis-cli INFO stats

High CPU Usage

Profile with occ:

kubectl exec -n nextcloudkup deploy/nextcloud -- \
  php occ config:system:set debug --value=true --type=boolean

Check logs for slow operations.