Solve "Document loading failed" errors with professional troubleshooting
#Problem Overview
#Solution Reference
This troubleshooting guide is based on the official Collabora Online proxy configuration documentation. For additional technical details and alternative setups, refer to:
This guide solves a complex issue where Nextcloud Office appears to connect to Collabora Online during tests, but fails when users try to open documents. Common in Cloudflare Tunnel + Apache + Docker environments.
Common Error Messages:
- "Document loading failed" - Failed to load Nextcloud Office
- "Could not detect any host" - LocalServerException in logs
- WebSocket connection failures - Socket closed unexpectedly
- 404 errors for browser resources and static assets
#Quick Fix (Most Common Solution)
90% of these issues are caused by Nextcloud's SSRF protection blocking localhost connections. Try this first:
# Edit Nextcloud config
sudo nano /var/www/nextcloud/config/config.php
# Add this line inside the $CONFIG array:
'allow_local_remote_servers' => true,
If this doesn't work, continue with the full diagnostic process below.
1
#Diagnostic Phase
#1.1 Check Nextcloud Logs
First, identify the specific error patterns:
# Find your Nextcloud data directory
sudo cat /var/www/nextcloud/config/config.php | grep datadirectory
# Monitor logs in real-time
sudo tail -f /path/to/your/data/nextcloud.log | grep -i "richdocuments\|office\|error"
#1.2 Verify Collabora Container
# Check if Collabora is running and listening
sudo ss -tlnp | grep 9980
# Test endpoints directly
curl -v http://127.0.0.1:9980/hosting/discovery
curl -v http://127.0.0.1:9980/hosting/capabilities
# Check container status
sudo docker ps | grep collabora
sudo docker logs --tail=20 collabora-container-name
#1.3 Test Built-in Connectivity
# Use Nextcloud's connectivity test
sudo -u www-data php /var/www/nextcloud/occ richdocuments:activate-config
Expected Success Output:
- ✓ Fetched /hosting/discovery endpoint
- ✓ Valid mimetype response
- ✓ Valid capabilities entry
- ✓ Detected WOPI server: Collabora Online
2
#Fix SSRF Protection
The most common cause is Nextcloud's security feature blocking local server connections:
# Edit Nextcloud configuration
sudo nano /var/www/nextcloud/config/config.php
# Add this line inside the $CONFIG array:
'allow_local_remote_servers' => true,
# Example placement:
$CONFIG = array (
'instanceid' => 'your_instance_id',
'passwordsalt' => 'your_salt',
'secret' => 'your_secret',
'trusted_domains' => array (
0 => 'your-domain.com',
),
'allow_local_remote_servers' => true, // Add this line
// ... rest of config
);
Security Note: This setting allows Nextcloud to make HTTP requests to local addresses. Only enable if you trust your local network and need it for services like Collabora.
3
#Configure Apache Reverse Proxy
For Cloudflare Tunnel environments, use the official SSL termination configuration:
#3.1 Enable Required Apache Modules
# Enable necessary modules
sudo a2enmod proxy
sudo a2enmod proxy_http
sudo a2enmod proxy_wstunnel
sudo a2enmod headers
sudo a2enmod rewrite
# Test and reload
sudo apache2ctl configtest
sudo systemctl reload apache2
#3.2 Update Virtual Host Configuration
# Edit your Apache virtual host
sudo nano /etc/apache2/sites-available/your-site.conf
# Replace Collabora section with this configuration:
# --- Collabora (CODE) reverse proxy ---
AllowEncodedSlashes NoDecode
ProxyPreserveHost On
# Static resources (CRITICAL for loading assets)
ProxyPass /browser http://127.0.0.1:9980/browser retry=0
ProxyPassReverse /browser http://127.0.0.1:9980/browser
# WOPI discovery URL
ProxyPass /hosting/discovery http://127.0.0.1:9980/hosting/discovery retry=0
ProxyPassReverse /hosting/discovery http://127.0.0.1:9980/hosting/discovery
# Capabilities
ProxyPass /hosting/capabilities http://127.0.0.1:9980/hosting/capabilities retry=0
ProxyPassReverse /hosting/capabilities http://127.0.0.1:9980/hosting/capabilities
# Main websocket (CRITICAL for real-time editing)
ProxyPassMatch "/cool/(.*)/ws$" ws://127.0.0.1:9980/cool/$1/ws nocanon
# Admin Console websocket
ProxyPass /cool/adminws ws://127.0.0.1:9980/cool/adminws
# Document operations
ProxyPass /cool http://127.0.0.1:9980/cool
ProxyPassReverse /cool http://127.0.0.1:9980/cool
# Legacy compatibility
ProxyPass /lool http://127.0.0.1:9980/cool
ProxyPassReverse /lool http://127.0.0.1:9980/cool
# --- end Collabora ---
Critical Configuration Points:
- /browser path is essential for CSS, JS, and images
- WebSocket configuration enables collaborative editing
- nocanon flag prevents URL issues
- All internal communication uses HTTP (not HTTPS)
4
#Configure Collabora for SSL Termination
Since Cloudflare Tunnel handles SSL termination, configure Collabora to expect HTTP internally but know it's behind HTTPS:
#4.1 Update SSL Settings
# Update SSL configuration for termination mode
sudo docker exec -it collabora-container sed -i 's/true<\/enable>/false<\/enable>/' /etc/coolwsd/coolwsd.xml
sudo docker exec -it collabora-container sed -i 's/true<\/termination>/' /etc/coolwsd/coolwsd.xml
# Restart to apply changes
sudo docker restart collabora-container
#4.2 Verify SSL Settings
# Check current SSL configuration
sudo docker exec collabora-container grep -A5 -B5 "ssl" /etc/coolwsd/coolwsd.xml
Correct SSL Termination Settings:
ssl.enable = false(HTTP internally)ssl.termination = true(Knows it's behind HTTPS)
5
#Test & Verify Solution
#5.1 Test Collabora Connectivity
sudo -u www-data php /var/www/nextcloud/occ richdocuments:activate-config
#5.2 Check Browser Console
Open Developer Tools (F12) → Console tab while trying to open a document. Look for:
- No 404 errors for /browser/* resources
- Successful WebSocket connections
- No "Mixed Content" warnings
#5.3 Monitor Real-time Logs
# Watch for errors during document opening
sudo tail -f /path/to/nextcloud.log | grep -i richdocuments
#5.4 Test Document Opening
Try opening different document types:
- .docx files (Word documents)
- .xlsx files (Excel spreadsheets)
- .pptx files (PowerPoint presentations)
🔧
#Advanced Troubleshooting
#Missing /browser Path
Symptom: 404 errors for static assets (CSS, JS, images)
Solution: Ensure the /browser proxy configuration is present and properly configured
#WebSocket Failures
Symptom: "Socket connection closed unexpectedly"
Solution: Enable proxy_wstunnel module and verify WebSocket proxy rules
#SSL Configuration Mismatch
Symptom: Mixed content errors, connection refused
Solution: Set Collabora to SSL termination mode (ssl.enable=false, ssl.termination=true)
#Additional Diagnostic Commands
# Check Apache error logs
sudo tail -f /var/log/apache2/error.log
# Test WebSocket connectivity
curl --include \
--no-buffer \
--header "Connection: Upgrade" \
--header "Upgrade: websocket" \
--header "Sec-WebSocket-Key: SGVsbG8gd29ybGQ=" \
--header "Sec-WebSocket-Version: 13" \
http://your-domain.com/cool/test/ws
# Check direct Collabora access
curl -I http://127.0.0.1:9980/browser/dist/bundle.js
🏆
#Success Verification
#You've successfully fixed Nextcloud Office when you see:
- Documents open immediately without loading screens
- No 404 errors in browser console
- WebSocket connections establish successfully
- Real-time collaborative editing works
- No errors in Nextcloud logs during document access
- All document types (.docx, .xlsx, .pptx) open properly
Environment-Specific Notes:
- Cloudflare Tunnel: Use HTTP internally, HTTPS externally
- Direct SSL: Use HTTPS URLs in proxy config
- Docker: Ensure container restart applies config changes
📚
#Prevention & Best Practices
#Best Practices for Prevention
- Document your setup: Keep notes on your specific configuration
- Test after updates: Nextcloud/Collabora updates can break configs
- Monitor logs: Set up log monitoring for early issue detection
- Backup configurations: Save working Apache and Collabora configs
- Use official configs: Stick to Collabora's recommended settings
Important: This configuration is specifically for SSL termination environments (Cloudflare Tunnel). For direct SSL setups, use HTTPS URLs in proxy configuration instead.