How to Fix ONLYOFFICE Document Server 502 Bad Gateway Behind Nginx

A browser shows “502 Bad Gateway” when opening an ONLYOFFICE Docs URL, or a Nextcloud/ownCloud connector cannot reach the document server. In both cases, Nginx is usually receiving a request but cannot get a valid response from its upstream. The upstream might be ONLYOFFICE’s internal document service, a Docker container, or another reverse proxy. First identify which Nginx returned the 502; then test the next hop directly before changing configuration.

ONLYOFFICE’s current Linux troubleshooting guide recommends checking the ds-docservice and ds-converter services and the Document Server logs. Its reverse-proxy guide also calls out forwarded host and protocol headers. The sequence below checks service health first, then Nginx routing and Docker networking.

1. Find out which Nginx is returning 502

ONLYOFFICE’s package installation includes its own Nginx configuration, and a deployment may also have an external Nginx reverse proxy. Docker can add another network hop. The 502 page’s appearance alone may not identify the layer, so compare the public URL with a local health check and the Nginx error log.

On a package-based Linux installation, test the local Document Server endpoint:

curl -i http://127.0.0.1/healthcheck

If the server is configured to serve ONLYOFFICE on a non-default local port, use that port instead. A healthy installation normally returns an HTTP success response with true. If this local request fails, fix the Document Server service before editing an outside proxy. If it succeeds locally but the public hostname returns 502, concentrate on the external Nginx upstream, protocol, headers, and firewall path.

Check which processes own the expected ports:

sudo ss -ltnp | grep -E ':(80|443|8080|8000)\b'

Ports vary by topology. A common Docker mapping publishes a host port such as 8080 to container port 80; a package installation can use its own Nginx on the host. Do not assume that 127.0.0.1:80 is the correct upstream simply because both services are on one machine.

2. Check the ONLYOFFICE services and logs

On a Linux package installation, inspect the document service and converter:

sudo systemctl status ds-docservice ds-converter
sudo journalctl -u ds-docservice -u ds-converter --since "15 minutes ago" --no-pager

ONLYOFFICE’s troubleshooting guide lists these services and identifies insufficient memory, a port 80 conflict, and service logs as things to check when Docs services fail to start. If a service is stopped, inspect its error first; then restart only the affected service:

sudo systemctl restart ds-docservice

The main Linux log directory is /var/log/onlyoffice/documentserver/. Check the Nginx error log and the docservice logs for messages such as “connection refused,” “upstream timed out,” or a missing file. These point to different causes: a refused connection usually means the upstream process or port is unavailable, while a timeout can mean the service is overloaded or stalled.

Also check available disk and memory if services are repeatedly exiting:

df -h
free -h

Do not keep restarting a failing service without reviewing its logs; a restart may briefly hide the symptom without fixing a port conflict, failed dependency, or resource problem.

3. Verify that Nginx points to the reachable upstream

Read the active virtual host and confirm the exact address and port in proxy_pass. From the machine or container where that Nginx runs, request the upstream directly. For example, if the container publishes port 80 as host port 8080:

curl -i http://127.0.0.1:8080/healthcheck

Replace the example address with the endpoint that is actually reachable from the proxy. If Nginx runs in a separate Docker container, 127.0.0.1 refers to that Nginx container itself, not the Docker host or the ONLYOFFICE container. Use a reachable service name on a shared Docker network or the correct host address and published port.

Check that the upstream scheme matches the backend. Use http:// if the backend listener speaks plain HTTP and https:// only if it is configured for TLS. Sending HTTP to a TLS port, or TLS to a plain HTTP port, can make a healthy service appear unavailable to Nginx.

4. Check forwarded headers and WebSocket proxying

ONLYOFFICE’s reverse-proxy guide says to preserve X-Forwarded-Proto and X-Forwarded-Host so the application knows the original protocol and hostname. The official Nginx examples also pass upgrade headers. If an external proxy is in front of ONLYOFFICE, compare its configuration with the official scenario that matches your topology.

A simplified example for a Docker container mapped to host port 8080 is shown below. Put the map directive inside Nginx’s http context, and adapt the hostname, TLS configuration, and upstream port to your setup:

map $http_upgrade $connection_upgrade {
    default upgrade;
    ''      close;
}

server {
    listen 443 ssl;
    server_name docs.example.com;

    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Host $host;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;
    }
}

This is a reference pattern, not a drop-in replacement for every installation. In particular, do not paste it over the packaged ONLYOFFICE Nginx configuration without understanding which server block owns ports 80 and 443. If Nginx shares the host with package-installed ONLYOFFICE, first confirm there is no port collision and route the external proxy to the internal listener configured for your deployment.

After editing, test the configuration before reloading Nginx:

sudo nginx -t
sudo systemctl reload nginx

If the configuration test fails, correct the reported file and line before reloading. A syntax error and an upstream 502 are separate problems; a successful nginx -t confirms syntax, not that the upstream responds.

5. If ONLYOFFICE runs in Docker, inspect its health and port mapping

Check whether the container is running and which host port is published:

docker ps --filter name=onlyoffice
docker port <container_name_or_id>
docker logs --tail 100 <container_name_or_id>

The official Docker install guide maps host ports to container port 80, and its example checks the container logs if the welcome page does not load. Use the port shown by docker port as the host-side upstream. When both Nginx and ONLYOFFICE are containers, put them on a shared network and route to the ONLYOFFICE service name and container port, rather than to the host’s loopback address.

Check the container’s health status if your Compose file defines a health check. The current upstream Compose example checks http://localhost:8000/info/info.json inside the container. A container that is “running” can still have an unhealthy document service. If it is restarting or unhealthy, use the logs to investigate database startup, memory, and configuration before changing the external proxy.

ONLYOFFICE documents persistent Docker paths for logs, certificates, and file cache. Avoid deleting volumes during troubleshooting; they may contain certificates or other data needed to recover the service.

6. Reload, test the health endpoint, and retest the integration

After correcting a confirmed issue, test the public hostname and compare it with the local endpoint:

curl -i https://docs.example.com/healthcheck

Use your real Document Server URL. A successful response at both the local upstream and public hostname shows that Nginx can reach the backend and return its health response. Then open the Document Server welcome page and retry the action that originally failed in Nextcloud, ownCloud, or your other connector.

If the health check succeeds but the connector still reports an error, the remaining problem may be outside the Nginx 502 path—for example, the connector URL, TLS trust, or JWT settings. Compare those values with the connector and ONLYOFFICE configuration rather than continuing to alter proxy timeouts blindly.

Quick diagnosis

Official references

• ONLYOFFICE Docs troubleshooting for Linux
• ONLYOFFICE Docs behind a proxy
• Official ONLYOFFICE Nginx HTTPS-to-HTTP proxy example
• ONLYOFFICE Docs Docker installation and port mapping
• ONLYOFFICE Document Server Compose example