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

File by id N not found (broken shares after storage migration)

Symptom: A shared file or folder shows an error banner or fails to open. The log shows StorageNotAvailableException: File by id <N> not found from SharedStorage or FailedStorage, often during quota lookups on PROPFIND.

Cause: The swarm migration switched primary storage to S3, which created new object::user:<uid> home storages with new fileids. Shares created before the migration still reference fileids on the old, no longer mounted home::<uid> storages, so Nextcloud cannot resolve the share source.

Diagnosis: List shares joined with their storage backend. Any share whose backend is home::<uid> or local::... is dead.

kubectl exec -n nextcloudaffenstall nextcloud-postgres-<primary> -c postgres -- \
  psql -U postgres -d nextcloud -c "
    SET search_path=nextcloud;
    SELECT sh.id, sh.uid_owner, sh.share_with, sh.file_target, st.id AS backend
    FROM oc_share sh
    JOIN oc_filecache fc ON fc.fileid = sh.file_source
    JOIN oc_storages st ON st.numeric_id = fc.storage
    ORDER BY sh.id;"

Solution:

  1. Restore missing content from the groot borg backup (repository on the Hetzner Storage Box, archives data-YYYY-MM-DD_HH:MM, path data/nextcloudaffenstall/data/<uid>/files/...).

  2. Upload the restored files through the Nextcloud VFS, because with S3 primary storage occ files:scan cannot import local files. Use a PHP script that bootstraps lib/base.php and writes via $rootFolder->getUserFolder($uid)->newFolder()/newFile()->putContent(), or occ files:put for single files into existing folders.

  3. Recreate the shares with the ShareManager API (\OCP\Share\IManager), matching the old share_type, share_with, and permissions.

  4. Delete the dead rows from oc_share.

  5. If new shares got a (2) suffix in file_target because the dead mounts still occupied the name, fix file_target after deleting the dead rows.

The full restore of all affenstall user homes performed on 2026-07-06 followed exactly this procedure. Content that had already been deleted into files_trashbin/ before the migration was recovered from the path-style S3 objects left behind by the January sync (same keys as the old data directory layout).

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.