Nextcloud admin warnings and how to fix them¶

This guide addresses common warnings that appear in the Nextcloud admin panel (Settings → Administration → Overview).

Wave H3: docker exec / docker compose use nextcloud--nextcloud--app and nextcloud--nginx--edge. Old names remain Docker DNS aliases only (REDIS_HOST, nginx upstreams, OnlyOffice internal URL).

Reverse proxy header configuration¶

Warning: "Die Konfiguration des Reverse-Proxy-Headers ist falsch. Dies stellt ein Sicherheitsproblem dar..."

Cause: Nextcloud doesn't trust the reverse proxy headers or forwarded headers are not configured.

Fix:

1. Apply proxy settings (for existing installs):

   01_scripts/scs-nextcloud-stack/apply-nextcloud-proxy-and-region.bash
   

2. If the warning persists, ensure the custom nginx config is in use:

   # From repo root
   cp 00_custom_configs/scs-nextcloud-stack/reverse-proxy/nginx.conf scs-nextcloud-stack/reverse-proxy/nginx.conf
   docker compose restart nextcloud--nginx--edge
   

3. Verify settings inside the container:

   docker exec nextcloud--nextcloud--app php /var/www/html/occ config:system:get trusted_proxies
   docker exec nextcloud--nextcloud--app php /var/www/html/occ config:system:get forwarded_for_headers
   

.mjs MIME type¶

Warning: "Der Webserver liefert .mjs-Dateien nicht mit dem JavaScript MIME-Typ..."

Cause: nginx doesn't serve .mjs files with the correct MIME type.

Fix:

Ensure custom nginx config is in use (includes .mjs handling):

cp 00_custom_configs/scs-nextcloud-stack/reverse-proxy/nginx.conf scs-nextcloud-stack/reverse-proxy/nginx.conf
docker compose restart nextcloud--nginx--edge

The custom config defines .mjs as application/javascript and includes it in the static file location block.

Maintenance window not configured¶

Warning: "Der Server hat keine konfigurierte Startzeit für das Wartungsfenster..."

Cause: Maintenance window start time and duration are not set.

Fix:

Apply maintenance window settings:

01_scripts/scs-nextcloud-stack/apply-nextcloud-proxy-and-region.bash

Or manually:

docker exec nextcloud--nextcloud--app php /var/www/html/occ config:system:set maintenance_window_start --type integer --value=22
docker exec nextcloud--nextcloud--app php /var/www/html/occ config:system:set maintenance_window_length --type integer --value=6

This sets the maintenance window to start at 22:00 (10 PM) for 6 hours.

Default phone region not set¶

Warning: "Für diese Installation ist keine Standard-Telefonregion festgelegt..."

Cause: default_phone_region is not configured.

Fix:

1. Add to .env:

   NEXTCLOUD_NEXTCLOUD_DEFAULT_PHONE_REGION=DE  # Use your ISO 3166-1 country code
   

2. Apply the setting:

   docker compose up -d nextcloud--nextcloud--app
   01_scripts/scs-nextcloud-stack/apply-nextcloud-proxy-and-region.bash
   

Or manually:

docker exec nextcloud--nextcloud--app php /var/www/html/occ config:system:set default_phone_region --value=DE

MIME type migrations available¶

Warning: "Eine oder mehrere MIME-Type-Migrationen sind verfügbar..."

Cause: After an upgrade, Nextcloud needs to update file MIME types in the database.

Fix:

Run the comprehensive repair script:

01_scripts/scs-nextcloud-stack/run-nextcloud-repair.bash

This runs occ maintenance:repair --include-expensive which includes MIME migrations. Can take a long time on large instances.

Missing database indices, columns, or primary keys¶

Warning: "Einige Spalten in der Datenbank fehlen eine Index..." or similar.

Cause: Database schema needs updates (common after upgrades or on older installs).

Fix:

Run the comprehensive repair script (handles all three):

01_scripts/scs-nextcloud-stack/run-nextcloud-repair.bash

Or manually:

docker exec nextcloud--nextcloud--app php /var/www/html/occ db:add-missing-indices
docker exec nextcloud--nextcloud--app php /var/www/html/occ db:add-missing-columns
docker exec nextcloud--nextcloud--app php /var/www/html/occ db:add-missing-primary-keys

MariaDB version warning¶

Warning: "MariaDB-Version '11.5.2-MariaDB-...' erkannt. Für optimale Leistung... wird MariaDB >= 10.6 und <= 11.4 empfohlen."

Cause: Nextcloud recommends MariaDB 10.6–11.4; you're running 11.5+.

Fix:

This is informational. MariaDB 11.5+ may work but is newer than Nextcloud's tested/recommended versions. Options:

1. Continue using 11.5+ — Monitor for issues; report bugs if you encounter problems specific to this version.
2. Downgrade to 11.4 — Requires database backup, container image change, and restore (not trivial).
3. Wait for Nextcloud to update recommendations — Future Nextcloud versions may officially support 11.5+.

For production, consider aligning with the recommended version range.

Email server not configured¶

Warning: "Die E-Mail-Serverkonfiguration wurde noch nicht festgelegt oder überprüft..."

Cause: SMTP or email settings are not configured.

Fix:

Configure email in Nextcloud admin:

1. Go to Settings → Administration → Basic settings → Email server
2. Choose mode (SMTP recommended)
3. Enter SMTP server, port, credentials
4. Test with "Send email" button

See detailed guide: Nextcloud email setup

.well-known URLs not resolving¶

Warning: "Der Webserver ist nicht ordnungsgemäß für die Auflösung von .well-known-URLs eingerichtet. Fehler bei: /.well-known/webfinger"

Cause: Either nginx is not correctly routing .well-known requests, redirects don't preserve the full URL through the reverse proxy chain (Traefik → nginx → Nextcloud), OR Nextcloud's overwrite.cli.url is set incorrectly, causing internal checks to fail.

Fix:

Ensure custom nginx config is in use (includes correct .well-known handling with full URL preservation):

cp 00_custom_configs/scs-nextcloud-stack/reverse-proxy/nginx.conf scs-nextcloud-stack/reverse-proxy/nginx.conf
docker compose restart nextcloud--nginx--edge

The custom config handles .well-known URLs with 301 redirects that preserve the full URL: - /.well-known/carddav → https://$host/remote.php/dav - /.well-known/caldav → https://$host/remote.php/dav - /.well-known/webfinger → https://$host/index.php/.well-known/webfinger - /.well-known/nodeinfo → https://$host/index.php/.well-known/nodeinfo - Other .well-known/* → https://$host/index.php$request_uri

Why this matters with reverse proxy: 1. nginx redirects: Using relative redirects like return 301 /index.php$request_uri fails because nginx doesn't know the external scheme (https) and hostname. By using $scheme://$host, we construct the full URL correctly. 2. Nextcloud internal checks: Nextcloud runs .well-known checks from inside the container using overwrite.cli.url. If this is set to https://localhost, checks will fail even if external access works. It must be set to your actual external domain.

Fix overwrite.cli.url:

docker exec nextcloud--nextcloud--app php /var/www/html/occ config:system:set overwrite.cli.url --value="https://your-nextcloud-domain.com"
docker exec nextcloud--nextcloud--app php /var/www/html/occ config:system:set overwritehost --value="your-nextcloud-domain.com"

Or use the apply script (includes this fix):

01_scripts/scs-nextcloud-stack/apply-nextcloud-proxy-and-region.bash

Test the fix:

docs/technical/troubleshooting/test-nextcloud-wellknown.bash your-nextcloud-domain.com

Or manually:

curl -I https://your-nextcloud-domain/.well-known/webfinger
# Should return 301 with Location header pointing to https://your-nextcloud-domain/index.php/.well-known/webfinger

Verify in Nextcloud: After restart, refresh the admin panel (Settings → Administration → Overview). The .well-known warning should disappear within a few minutes.

If warning persists (false positive):

The warning may persist even though .well-known URLs work perfectly for external clients. This happens when: - The Nextcloud container can't reach its own external domain from inside - The request path through Traefik creates a routing loop - SSL certificate verification fails for internal checks

Verify it's a false positive:

# Test external access (should work)
curl -I https://your-nextcloud-domain/.well-known/webfinger

# If external access works but admin warning persists, it's a false positive

Option A: Suppress the check (recommended if URLs work externally)

docker exec nextcloud--nextcloud--app php /var/www/html/occ config:app:set serverinfo check_well_known --value=false

Option B: Add domain to container hosts Edit 00_custom_configs/scs-nextcloud-stack/docker/docker-compose.override.yml:

nextcloud--nextcloud--app:
  extra_hosts:
    - "your-nextcloud-domain.com:172.18.0.1"  # Point to Traefik gateway

Then restart:

docker compose up -d nextcloud--nextcloud--app

Note: If external access to .well-known URLs works (CalDAV, CardDAV, federation), the warning is cosmetic and can be safely ignored or suppressed.

AppAPI deployment daemon not configured¶

Warning: "Der Standard-Deploy-Daemon von AppAPI ist nicht eingerichtet..."

Cause: AppAPI (external apps framework) is installed but no deployment daemon is registered.

Impact: Only relevant if you want to install external apps (Ex-Apps) from the Nextcloud app ecosystem. Core Nextcloud functionality is not affected.

Fix (if you need external apps):

1. Go to Settings → Administration → AppAPI
2. Register a deployment daemon (Docker socket, manual, or external)
3. Set it as default

Fix (if you don't need external apps):

Ignore this warning or disable the AppAPI app:

docker exec nextcloud--nextcloud--app php /var/www/html/occ app:disable app_api

Warnings in logs¶

Warning: "X Warnungen in den Protokollen seit..."

Cause: Various issues logged by Nextcloud (performance, deprecations, errors).

Fix:

1. View logs: Settings → Administration → Logging
2. Review each warning and address as needed
3. Common issues:
4. Deprecation warnings: Inform app developers; update apps when available
5. Performance warnings: Optimize database, enable caching (Redis), check server resources
6. PHP warnings: May indicate app bugs; report to app developers
7. File access errors: Check file permissions on volumes

Clear old log entries after addressing issues:

docker exec nextcloud--nextcloud--app php /var/www/html/occ log:manage --clear

Caching not configured¶

Warning: "Kein Speicher-Cache konfiguriert..."

Cause: Nextcloud is not using Redis or APCu for caching.

Fix:

Redis is already included in the stack. Verify it's configured:

docker exec nextcloud--nextcloud--app php /var/www/html/occ config:system:get memcache.distributed
docker exec nextcloud--nextcloud--app php /var/www/html/occ config:system:get memcache.locking
docker exec nextcloud--nextcloud--app php /var/www/html/occ config:system:get redis host

If not configured, set Redis:

docker exec nextcloud--nextcloud--app php /var/www/html/occ config:system:set memcache.distributed --value='\OC\Memcache\Redis'
docker exec nextcloud--nextcloud--app php /var/www/html/occ config:system:set memcache.locking --value='\OC\Memcache\Redis'
docker exec nextcloud--nextcloud--app php /var/www/html/occ config:system:set redis host --value=nextcloud--redis
docker exec nextcloud--nextcloud--app php /var/www/html/occ config:system:set redis port --value=6379 --type=integer

Background jobs not running¶

Warning: "Last background job execution ran X ago. Something seems wrong."

Cause: Nextcloud cron is not running or configured incorrectly.

Fix:

1. Check background jobs setting: Settings → Administration → Basic settings → Background jobs
2. Ensure "Cron" is selected (not AJAX or Webcron)
3. Verify cron is running inside the container:

   docker exec nextcloud--nextcloud--app cat /var/spool/cron/crontabs/www-data
   

Should show:

*/5 * * * * php -f /var/www/html/cron.php

1. If missing, the Nextcloud image should set this up automatically. Restart the container:

   docker compose restart nextcloud--nextcloud--app
   

2. Manually trigger cron to test:

   docker exec -u www-data nextcloud--nextcloud--app php /var/www/html/cron.php
   

DOCX (and other Office files) not opening in OnlyOffice¶

Symptom: Clicking DOCX, XLSX, or PPTX files downloads them instead of opening in OnlyOffice, or shows an error. Logs may show Error occurred in the document service: Invalid token or checkJwt error: invalid signature.

Common causes and fixes:

1. JWT secret mismatch (Invalid token / invalid signature)¶

Nextcloud and the OnlyOffice Document Server must share the same JWT secret. If NEXTCLOUD_ONLYOFFICE_JWT_SECRET is empty in .env, the Document Server gets a random secret on start, causing signature mismatch.

Fix: Run the JWT fix script:

01_scripts/scs-nextcloud-stack/fix-onlyoffice-jwt.bash

Then add the printed secret to your .env:

NEXTCLOUD_ONLYOFFICE_JWT_SECRET=<the-secret-from-script-output>

Without this in .env, the mismatch will return on the next docker compose up.

2. Re-save OnlyOffice connector settings¶

Connector settings can be lost after upgrades or config changes. Re-saving often fixes the issue:

1. Go to Settings → Administration → OnlyOffice
2. Verify Document Server URL and JWT secret match your .env
3. Click Save

3. Collabora (richdocuments) conflict¶

If both OnlyOffice and Collabora (richdocuments) are enabled, Collabora can override OnlyOffice's file associations. Check:

docker exec nextcloud--nextcloud--app php /var/www/html/occ app:list | grep -E "onlyoffice|richdocuments"

If richdocuments is enabled and you want OnlyOffice for DOCX/XLSX/PPTX, disable Collabora:

docker exec nextcloud--nextcloud--app php /var/www/html/occ app:disable richdocuments

4. File extension case sensitivity¶

Some setups only handle lowercase extensions. Try files named document.docx (lowercase) instead of document.DOCX.

5. Verify OnlyOffice configuration¶

docker exec nextcloud--nextcloud--app php /var/www/html/occ config:list onlyoffice

Ensure: - DocumentServerUrl is your external OnlyOffice URL (e.g. https://office.yourdomain.com/) - StorageUrl is your Nextcloud URL - jwt_secret matches NEXTCLOUD_ONLYOFFICE_JWT_SECRET in .env

6. Test Document Server connectivity¶

docker exec nextcloud--nextcloud--app php /var/www/html/occ onlyoffice:documentserver --check

6b. Converter / thumbnails: HTTP 504 Gateway Time-out (/converter)¶

If logs show failures when Nextcloud POSTs internally to OnlyOffice (http://nextcloud--onlyoffice-document-server/converter), the bottleneck is usually the default nginx proxy read timeout (~60 s) inside the Document Server image while the converter renders previews.

The deployment binds scs-nextcloud-stack/onlyoffice-document-server/ds-timeout.conf (via SCS_ROOT_PATH in 00_custom_configs/.../docker-compose.override.yml) to raise those timeouts to 600 s. After changing that file, recreate the Document Server container: docker compose up -d nextcloud--onlyoffice-document-server.

6c. https://office.… returns 404 (404 page not found, plain text)¶

Traefik’s default 404 means no valid router for that host. Check Traefik logs for:

middleware "rate-limit-onlyoffice@docker" does not exist

Middleware labels on the Traefik container (scs--reverse-proxy) are not applied as Docker-provider middlewares. The rate-limit must be declared on a backend service (this repo: nextcloud--onlyoffice-reverse-proxy in 00_custom_configs/scs-nextcloud-stack/docker/docker-compose.override.yml). After fixing labels, recreate: docker compose up -d --force-recreate nextcloud--onlyoffice-reverse-proxy.

7. Check OnlyOffice logs¶

docker compose logs nextcloud--onlyoffice-document-server --tail 100

Summary: Fix all common warnings¶

Run the fix-all script from the repo root:

01_scripts/scs-nextcloud-stack/fix-nextcloud-warnings.bash

Or run the steps manually:

# 1. Restart reverse proxy (picks up nginx config: .well-known URLs, etc.)
docker compose restart nextcloud--nginx--edge

# 2. Apply proxy, maintenance window, phone region, overwritecondaddr
01_scripts/scs-nextcloud-stack/apply-nextcloud-proxy-and-region.bash

# 3. Run comprehensive maintenance (MIME migrations, DB indices, columns, keys)
01_scripts/scs-nextcloud-stack/run-nextcloud-repair.bash

For email and AppAPI, configure manually via the Nextcloud admin UI as needed.