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 “Enable OnlyOffice Debug Mode” 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

In the docker-compose.yaml file of onlyoffice:

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 your 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
6

onlyoffice:
  environment:
    - JWT_ENABLED=true
    - JWT_SECRET=your-generated-secret  # MUST match FileBrowser exactly
    - JWT_HEADER=Authorization
    - ALLOW_PRIVATE_IP_ADDRESS=true # This configuration allows private ip address on DNS lookup

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"

API Connection Errors link

This is most common for users running behind a reverse proxy. If you have all correctly configured but you can’t open any document, make sure that the API of onlyoffice is reachable, you can check this by visiting this URL in the browser or using the curl command:

1

http://<office-server>/web-apps/apps/api/documents/api.js # http or https with domain name if behind reverse proxy

Possible causes:

• Wrong reverse proxy configuration: Make sure that you reverse proxy is properly configured.
• CORS Issues: If accessing from a different domain, ensure CORS is configured in you reverse proxy.
• Firewall issues: Make sure that you don’t have firewalls that can be interferring.
• Connection errors.

If using docker, make sure that you are using the official onlyoffice image, since some from third parties have some custom configurations that might be conflicting.

Private IP addresses link

OnlyOffice blocks private IP addresses (like 192.168.x.x) by default for security. This occurs when using internal URLs in your configuration.

To fix this you’ll need to add an environment variable to your onlyoffice compose file:

1
2
3
4
5

onlyoffice:
  environment:
    - JWT_ENABLED=true
    - JWT_SECRET=your-secret
    - ALLOW_PRIVATE_IP_ADDRESS=true # Add this

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).

Download Fails link

Always look at the only office server logs for clues when you see “Download Failed” for clues that filebrowser itself can’t see.

Some have also found the need for ALLOW_PRIVATE_IP_ADDRESS=true:

1
2
3
4
5
6

onlyoffice:
  environment:
    - JWT_ENABLED=true
    - JWT_SECRET=your-generated-secret  # MUST match FileBrowser exactly
    - JWT_HEADER=Authorization
    - ALLOW_PRIVATE_IP_ADDRESS=true # This configuration allows private ip address on DNS lookup

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