Troubleshooting

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

Enable Debug logging and Debug Mode link

If you are having persistent issues with OnlyOffice, the first thing should be to enable debugger mode.

Enable Frontend Debug Mode link

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

Enable FileBrowser server debug logs link

Configure filebrowser to run with debug logging

Enable OnlyOffice service debug logs link

1
2
3

onlyoffice:
  environment:
    - LOG_LEVEL=DEBUG

Quick Diagnostics link

Verify OnlyOffice is Running link

1
2
3
4
5
6
7
8

# Check health endpoint
curl http://<onlyoffice-server>/healthcheck

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

# Check welcome page
curl http://<onlyoffice-server>/welcome

Common Issues link

OnlyOffice Server Not Found link

Solutions:

Verify OnlyOffice is running:

1
2
3
4
5

# Check Docker container status
docker ps | grep onlyoffice

# Check service health
curl http://<onlyoffice-server>/healthcheck

Expected response:

1

{"status":"ok"}

FileBrowser needs correct URLs:

1
2
3
4

integrations:
  office:
    url: "http://<onlyoffice-server>"       # 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:

1
2
3
4
5

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

# Or use uuidgen
uuidgen

Step 2: Configure FileBrowser

1
2
3
4

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

Step 3: Configure OnlyOffice

1
2
3
4
5

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

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.

1
2
3
4
5
6
7
8

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

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34

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

1
2
3
4
5
6
7
8
9

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

integrations:
  office:
    url: "https://office.yourdomain.com"
    internalUrl: "https://onlyoffice" # (optional) this is the internal url that the filebrowser server can communicate with directly. otherwise url is used
    secret: "your-secret"

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

# 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;

        # Timeouts
        proxy_connect_timeout 300s;
        proxy_send_timeout 300s;
        proxy_read_timeout 300s;
    }
}

1
2
3
4
5

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

Advanced Configuration link

External and Internal URLs link

See Configuration

Why two URLs?

• Browser → The browser always uses integrations.office.url to connect from your browser to only office server.
• OnlyOffice → Uses either server.externalUrl or server.internalUrl for downloading/saving files to FileBrowser server.
• FileBrowser → Uses either integratons.office.internalUrl or integrations.office.url to connect from the filebrowser server to OnlyOffice server.

Performance Issues link

Slow Document Loading link

Document loading can be quite slow because of the many components onlyoffice needs to talk to. The best way to improve document loading times it to set server.internalUrl so OnlyOffice can communicate directly with filebrowser (it’s possible on same private network).

Getting Help link

Gather Information link

When asking for help, provide:

1. Logs: Most imprtantly relevant debug logs from the server, as well as OnlyOffice server logs.
2. Debug mode output (screenshot from browser)
3. Browser console errors (F12 → Console tab)

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