Nextcloud Office + Collabora Fix Guide

Revision as of Jun 25, 2026 22:26 by migration. This is an old revision — view current.

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:

📖 Collabora Online - Proxy Settings Documentation

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.

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

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.

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)

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)

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.

← Back to theLAB Wiki

Nextcloud Office + Collabora Fix Guide

#Problem Overview

#Solution Reference

#Quick Fix (Most Common Solution)

#Diagnostic Phase

#1.1 Check Nextcloud Logs

#1.2 Verify Collabora Container

#1.3 Test Built-in Connectivity

#Fix SSRF Protection

#Configure Apache Reverse Proxy

#3.1 Enable Required Apache Modules

#3.2 Update Virtual Host Configuration

#Configure Collabora for SSL Termination

#4.1 Update SSL Settings

#4.2 Verify SSL Settings

#Test & Verify Solution

#5.1 Test Collabora Connectivity

#5.2 Check Browser Console

#5.3 Monitor Real-time Logs

#5.4 Test Document Opening

#Advanced Troubleshooting

#Missing /browser Path

#WebSocket Failures

#SSL Configuration Mismatch

#Additional Diagnostic Commands

#Success Verification

#You've successfully fixed Nextcloud Office when you see:

#Prevention & Best Practices

#Best Practices for Prevention