// troubleshooting guide · seafile

Seafile OnlyOffice 'Download Failed' Error

Status
Workaround available
platforms:
Web, self-hosted server
updated:
November 16, 2026
reports:
4
Method
how we research
Share

RUNBOOK · seafile/onlyoffice-download-failed5 FIXES

// quick answer

Seafile 12+ forces JWT, so the secret must match on both sides, and the OnlyOffice server must be able to reach your Seafile URL. In Seafile 13, subpath setups also need the proxy to pass X-Forwarded-Host.

Most likely fix: Match the JWT secret

How to fix it

// try these in order, the most common fix is first

  1. FIX 1Match the JWT secret

    1. 01Set ONLYOFFICE_JWT_SECRET in Seafile's .env
    2. 02Use the same value in seahub_settings.py and in the OnlyOffice container
    3. 03Restart both containers
    Did this fix it?
  2. FIX 2Set the correct API URL

    1. 01In seahub_settings.py set ONLYOFFICE_APIJS_URL = 'https://yourdomain/onlyofficeds/web-apps/apps/api/documents/api.js'
    2. 02Restart Seahub
    Did this fix it?
  3. FIX 3Pass X-Forwarded-Host for subpaths

    1. 01In your external proxy (e.g. Caddy) route /onlyofficeds/* to the OnlyOffice container
    2. 02Add header_up X-Forwarded-Host {host} so OnlyOffice builds correct URLs
    3. 03Reload the proxy
    Did this fix it?
  4. FIX 4Let OnlyOffice reach Seafile

    1. 01If the domain doesn't resolve inside the container, add an extra_hosts entry mapping it to the host IP
    2. 02Watch docker logs -f seafile-onlyoffice while opening a file to see the failing URL
    Did this fix it?
  5. FIX 5Pin a working version

    1. 01If the error started after an update, pin the previous OnlyOffice image tag until a fix is released
    Did this fix it?

SANDBOX · seafile RUNS IN YOUR BROWSER

Try it: upload, share and sync files between the web and your laptop

A hands-on Seafile-style sandbox, including the spots where users get stuck. See where problems like this one start. 1-2 minutes, nothing is saved.

Symptoms

Office files open in OnlyOffice but show 'Download failed', or the editor stays blank.

Why it happens

  • C-01JWT secret in .env and seahub_settings.py doesn't match
  • C-02OnlyOffice container can't resolve or reach the Seafile domain
  • C-03OnlyOffice served under /onlyofficeds without the right forwarded host
  • C-04Seafile 13 bundled Nginx no longer editable, so old subfolder config is gone
  • C-05Version regressions after an OnlyOffice or Seafile update

// this guide also covers

  • seafile onlyoffice download failed
  • seafile onlyoffice not working
  • seafile onlyoffice jwt
  • seafile 13 onlyoffice

Still not working?

If Seafile keeps failing, you're not alone. See every Seafile problem users report or the alternatives people switch to.

Have an app idea? Our small team builds any software: web and mobile apps, games, desktop, AI tools. Price agreed together.

Talk to us

Watch Seafile Get an email when its price changes, it has an outage, or we publish a new fix. No spam.

Fixed it? Share this guide

The same problem in other apps

All not loading, error messages & connection guides →

Other Seafile errors

All 11 Seafile errors and fixes →