Troubleshooting

Solutions for common OnlyOffice integration problems including connectivity, authentication, and document opening issues.

Debug Mode (Recommended First Step) link

The easiest way to troubleshoot OnlyOffice issues is to use the built-in debug mode:

Enable Debug Mode:

1. Navigate to Profile Settings → File Viewer Options
2. Toggle “Debug OnlyOffice Editor” to ON
3. Open any document with OnlyOffice
4. View the debug tooltip that appears automatically

What Debug Mode Shows link

The debug tooltip provides:

• Real-time trace of the integration process
• Network flow analysis between components
• Configuration details including URLs and domains
• Specific error detection with troubleshooting advice
• Connectivity testing to OnlyOffice server

Network Flow Diagram link

The diagram shows the communication flow:

1. Browser ↔ OnlyOffice Server: Editor interface
2. OnlyOffice → FileBrowser (download URL): Fetches document
3. OnlyOffice → FileBrowser (callback URL): Saves changes

Quick Diagnostics link

Verify OnlyOffice is Running link

# Check health endpoint
curl http://localhost/healthcheck

# Expected response:
{"status":"ok"}

# Check welcome page
curl http://localhost/welcome

Test Network Connectivity link

From FileBrowser container:

# Test connection to OnlyOffice
docker exec filebrowser curl http://onlyoffice/healthcheck

Check Browser Console link

Open browser developer tools (F12) and look for:

Successful Config:

OnlyOffice config request: source=downloads, path=/doc.docx, isShare=false
OnlyOffice: built download URL=http://localhost:8080/api/raw?...
OnlyOffice: successfully generated config for file=doc.docx

Successful Save:

OnlyOffice callback: source=downloads, path=/doc.docx, status=2
OnlyOffice: successfully saved updated document

Common Issues link

OnlyOffice Server Not Found link

Solutions:

Verify OnlyOffice is running:

# Check Docker container status
docker ps | grep onlyoffice

# Check service health
curl http://localhost:80/healthcheck

Expected response:

{"status":"ok"}

If not running, start OnlyOffice:

docker-compose up -d onlyoffice

FileBrowser needs correct URLs:

integrations:
  office:
    url: "http://onlyoffice.yourdomain.com"       # Must be accessible from browser
    secret: "your-jwt-secret"

Test the URL from your browser: Navigate to the OnlyOffice URL - you should see a welcome page.

JWT Authentication Errors link

Step 1: Generate JWT Secret

Create a strong random secret:

# Generate 32-byte base64 secret
openssl rand -base64 32

# Or use uuidgen
uuidgen

Step 2: Configure FileBrowser

integrations:
  office:
    url: "http://onlyoffice"
    secret: "your-generated-secret"  # Use the secret from Step 1

Step 3: Configure OnlyOffice

onlyoffice:
  environment:
    - JWT_ENABLED=true
    - JWT_SECRET=your-generated-secret  # MUST match FileBrowser exactly
    - JWT_HEADER=Authorization

Documents Won’t Open link

Solutions:

1. Check File Format Support

OnlyOffice supports these formats:

2. Verify File Permissions

# Check file permissions
ls -l /path/to/document.docx

# FileBrowser user must have read access
-rw-r--r-- 1 user group 12345 date document.docx

3. Check File Size Limits

Large files may timeout. Increase limits:

onlyoffice:
  environment:
    - MAX_FILE_SIZE=100  # MB

4. Review Logs

# FileBrowser logs
docker logs filebrowser --tail 100

# OnlyOffice logs
docker logs onlyoffice --tail 100

# Follow logs in real-time
docker-compose logs -f

HTTPS and SSL/TLS Issues link

OnlyOffice does not work with HTTPS out of the box when behind a reverse proxy. You need proper SSL configuration.

integrations:
  office:
    url: "http://localhost:8080"

onlyoffice:
  environment:
    - JWT_ENABLED=true
    - JWT_SECRET=your-secret

filebrowser:
  image: gtstef/filebrowser
  labels:
    - "traefik.enable=true"
    - "traefik.http.routers.filebrowser.rule=Host(`files.yourdomain.com`)"
    - "traefik.http.routers.filebrowser.entrypoints=websecure"
    - "traefik.http.routers.filebrowser.tls.certresolver=letsencrypt"
    - "traefik.http.services.filebrowser.loadbalancer.server.port=80"
  networks:
    - proxy

onlyoffice:
  image: onlyoffice/documentserver
  environment:
    - JWT_ENABLED=true
    - JWT_SECRET=your-secret
    - JWT_HEADER=Authorization
    - ONLYOFFICE_HTTPS_HSTS_ENABLED=false
  labels:
    - "traefik.enable=true"
    - "traefik.http.routers.onlyoffice.rule=Host(`office.yourdomain.com`)"
    - "traefik.http.routers.onlyoffice.entrypoints=websecure"
    - "traefik.http.routers.onlyoffice.tls.certresolver=letsencrypt"
    - "traefik.http.services.onlyoffice.loadbalancer.server.port=80"
    # Required headers for OnlyOffice
    - "traefik.http.routers.onlyoffice.middlewares=onlyoffice-headers"
    - "traefik.http.middlewares.onlyoffice-headers.headers.customrequestheaders.X-Forwarded-Proto=https"
    - "traefik.http.middlewares.onlyoffice-headers.headers.accesscontrolalloworiginlist=*"
  networks:
    - proxy

networks:
  proxy:
    external: true

server:
  externalUrl: "https://files.yourdomain.com"
  internalUrl: "http://filebrowser:80"

integrations:
  office:
    url: "https://office.yourdomain.com"
    internalUrl: "https://files.yourdomain.com"
    secret: "your-secret"

# OnlyOffice upstream
upstream onlyoffice {
    server onlyoffice:80;
}

server {
    listen 443 ssl http2;
    server_name office.yourdomain.com;

    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location / {
        proxy_pass http://onlyoffice;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        
        # WebSocket support
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        
        # Timeouts
        proxy_connect_timeout 300s;
        proxy_send_timeout 300s;
        proxy_read_timeout 300s;
    }
}

integrations:
  office:
    url: "https://office.yourdomain.com"
    internalUrl: "http://onlyoffice:80"
    secret: "your-secret"

Advanced Configuration link

External and Internal URLs link

server:
  externalUrl: "https://files.yourdomain.com"  # Accessible from browser
  internalUrl: "http://filebrowser:80"         # Accessible from OnlyOffice container

integrations:
  office:
    url: "https://office.yourdomain.com"       # Accessible from browser
    internalUrl: "https://files.yourdomain.com" # For OnlyOffice → FileBrowser callbacks
    secret: "your-jwt-secret"

Why two URLs?

• Browser → OnlyOffice: Uses integrations.office.url
• OnlyOffice → FileBrowser: Uses internalUrl for downloading/saving files
• Internal URLs can use Docker service names for better performance

Performance Issues link

Slow Document Loading link

Solutions:

1. Increase OnlyOffice Resources

onlyoffice:
  deploy:
    resources:
      limits:
        memory: 4G
        cpus: '2.0'
      reservations:
        memory: 2G
        cpus: '1.0'

2. Use Persistent Storage

onlyoffice:
  volumes:
    - onlyoffice_data:/var/www/onlyoffice/Data
    - onlyoffice_logs:/var/log/onlyoffice

volumes:
  onlyoffice_data:
  onlyoffice_logs:

3. Optimize Timeouts

# Traefik
serversTransport:
  forwardingTimeouts:
    dialTimeout: "60s"
    responseHeaderTimeout: "75s"
    idleConnTimeout: "90s"

# nginx
proxy_connect_timeout 300s;
proxy_send_timeout 300s;
proxy_read_timeout 300s;

Connection Timeouts link

Check and increase timeouts at multiple levels:

Traefik:

http:
  serversTransports:
    default:
      forwardingTimeouts:
        dialTimeout: "30s"
        responseHeaderTimeout: "60s"
        idleConnTimeout: "90s"

OnlyOffice:

environment:
  - TIMEOUT=300

Test Network Latency:

# Test response time
time curl http://onlyoffice/healthcheck

# Check network path
docker exec filebrowser ping onlyoffice

Troubleshooting Checklist link

Use this checklist when debugging OnlyOffice issues:

• Enable debug mode in FileBrowser profile settings
• Check OnlyOffice is running: docker ps | grep onlyoffice
• Verify health endpoint: curl http://onlyoffice/healthcheck
• Test from browser: Navigate to OnlyOffice URL, see welcome page
• Check JWT secrets match in both configurations
• Verify network connectivity between containers
• Check browser console for JavaScript errors
• Review logs from both FileBrowser and OnlyOffice
• Verify file format is supported
• Check file permissions and size limits
• Test with HTTPS disabled (if using SSL)
• Verify externalUrl and internalUrl are set correctly

Getting Help link

Gather Information link

When asking for help, provide:

1. FileBrowser version:

docker exec filebrowser ./filebrowser version

2. OnlyOffice version:

docker exec onlyoffice /var/www/onlyoffice/documentserver/npm/json -f /var/www/onlyoffice/documentserver/package.json version

3. Configuration (sanitized - remove secrets):

integrations:
  office:
    url: "https://office.example.com"
    secret: "REDACTED"

4. Logs:

docker logs onlyoffice --tail 100
docker logs filebrowser --tail 100

5. Debug mode output (screenshot from browser)

6. Browser console errors (F12 → Console tab)

Test OnlyOffice Independently link

Verify OnlyOffice works standalone:

# Visit welcome page
curl http://localhost/welcome

# Should return HTML with OnlyOffice welcome page

Enable Verbose Logging link

onlyoffice:
  environment:
    - LOG_LEVEL=DEBUG

Community Resources link

• GitHub Issues - Report bugs
• GitHub Discussions - Ask questions
• OnlyOffice Documentation - Official OnlyOffice docs
• Community Configurations - Working examples

Next Steps link

• Configuration - Set up OnlyOffice integration
• Office guides - Usage examples and best practices
• About OnlyOffice - Features and capabilities