The Free Encyclopedia
Log in
Article History

Nextcloud Office + Collabora Fix Guide

Revision as of Jun 25, 2026 23:43 by migration.

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