websocket Connection failed

[fengluo2]

Description

The system uses Docker and a reverse proxy
Locally, wscat can connect and receive ping messages
however, the browser indicates a connection failure

TriliumNext Version

0.99.3

What operating system are you using?

Ubuntu

What is your setup?

Server access only

Operating System Version

ubuntu24

Error logs

There were no obvious error messages; the browser console was just constantly trying to reconnect.

[dosubot[bot]]

Hi @fengluo2! I'm Dosu and I’m helping the Trilium team.

The most common cause of browser WebSocket connection failures with Trilium behind a reverse proxy is missing WebSocket upgrade headers in your proxy configuration. Tools like wscat can connect because they bypass browser restrictions, but browsers require the proxy to forward specific headers for WebSocket handshakes to work over HTTPS.

For Caddy, your Caddyfile should include:

example.com {
    reverse_proxy http://trilium:8080 {
        header_up Host {host}
        header_up X-Forwarded-Proto {scheme}
        header_up Upgrade {http.upgrade}
        header_up Connection {http.connection}
    }
}

For Nginx, use:

proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection 'upgrade';
proxy_set_header Host $host;
proxy_cache_bypass $http_upgrade;

If you use Apache, enable the proxy_wstunnel module and follow the official setup guide.

After updating your proxy config, reload the proxy and clear your browser cache. If it still fails, check your proxy logs for errors during the WebSocket handshake and confirm Docker networking allows the proxy to reach Trilium. More details and examples are in this issue and this comment.

If you share your proxy config, I can help review it for any missing settings.

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}    

[fengluo2]

A successful local test should mean the reverse proxy configuration is working correctly, right? @dosu

[dosubot[bot]]

Not necessarily—wscat can connect even if the reverse proxy isn’t fully set up for browsers. Browsers have stricter requirements: your proxy must forward specific headers (like Upgrade, Connection, Host, X-Forwarded-Proto, etc.) and use HTTP/1.1 for WebSocket support. You also need to set Trilium’s trustedReverseProxy option so it trusts headers from the proxy. If any of these are missing, browsers will fail to connect even if CLI tools work. See this discussion and the official docs for details.

If you want to double-check, review your proxy config for those headers, confirm trustedReverseProxy=true in Trilium’s config, and try a hard refresh in your browser after making changes. If you’re still stuck, sharing your proxy config can help pinpoint what’s missing.

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}    

[fengluo2]

OpenResty

    location / {
        proxy_set_header Host $host; 
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; 
        proxy_set_header X-Forwarded-Host $server_name; 
        proxy_set_header X-Real-IP $remote_addr; 
        proxy_set_header X-Forwarded-Proto $scheme; 
        proxy_set_header Connection upgrade;
        proxy_set_header Upgrade $http_upgrade; 
        proxy_http_version 1.1; 
        proxy_pass http://127.0.0.1:8081; 
    }

@dosu

[dosubot[bot]]

Your OpenResty config includes the right headers for WebSocket support, and trustedReverseProxy is set in Trilium, which are both required for browser WebSocket connections. One thing to double-check: your proxy_pass points to http://127.0.0.1:8081, but Trilium’s default port is 8080—make sure Trilium is actually running on 8081, or update either the proxy or Trilium’s config.ini so the ports match. A mismatch here will cause connection failures even if everything else is correct.

If the ports are aligned, try clearing your browser cache and cookies, then reload. If it still fails, check both OpenResty and Trilium logs for errors during the WebSocket handshake—look for upgrade or authentication/session issues. Sometimes, browser cache or HSTS can cause persistent failures even after fixing the proxy config.

If you’re still stuck after these checks, let me know what you see in the logs or if there are any error messages in the browser’s network tab.

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}    

[fengluo2]

The problem persists even after changing it to 8081.
OpenResty has no error logs.
The Docker container also has no error logs.
So I'm very confused.
Moreover, the web page always loads normally.

@dosu

[dosubot[bot]]

Your setup and headers look correct, but when wscat works and browsers don't, it's almost always a subtle proxy or session issue. Browsers require the proxy to forward Upgrade and Connection headers exactly as expected, and sometimes CLI tools succeed even if the proxy isn't forwarding them perfectly for browsers. This is a common problem with reverse proxies and Trilium—see similar cases and solutions here and here.

Here’s what to try next:

1. Open your browser’s developer tools (Network tab), attempt to load Trilium, and look for the WebSocket request. Check the status code and any error details—if you see a 400/403/502 or CORS/session error, that’s a clue.
2. Confirm the browser is using the exact same URL and protocol (http/https) as your proxy is configured for.
3. Compare the request headers (especially cookies and authentication/session headers) between wscat and the browser. Sometimes, browser sessions or cookies are missing or invalid.
4. Try a hard refresh (Ctrl+Shift+R) and clear your browser cache—stale assets or HSTS can cause persistent failures.
5. If you’re using HTTPS, make sure there’s no certificate mismatch or mixed content warning in the browser.

If the browser’s network tab shows the WebSocket handshake never reaches the backend (no 101 Switching Protocols), the proxy is still not forwarding the upgrade request correctly—even if the config looks right. Double-check for typos or extra whitespace in your OpenResty config, and try temporarily removing extra headers to isolate the issue.

If you can share the browser’s network error details or a screenshot of the failed WebSocket request, I can help pinpoint the problem further.

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}    

[fengluo2]

I tried enabling HTTPS directly in the configuration file, and WSS worked fine. However, the same problem occurred when using a reverse proxy (wss->wss). It seems to be a reverse proxy issue. I'll try modifying the reverse proxy configuration again. This issue can be closed now.

[fengluo2]

This is my complete configuration. You can try it out using nginx + docker to see if it can proxy properly. I don't plan to use a proxy anymore; I'll just use the built-in SSL certificate.

server {
    listen 80 ; 
    listen 443 ssl ; 
    server_name ******; 
    index index.php index.html index.htm default.php default.htm default.html; 
    access_log /www/sites/******/log/access.log main; 
    error_log /www/sites/******/log/error.log; 
    location ~ ^/(\.user.ini|\.htaccess|\.git|\.env|\.svn|\.project|LICENSE|README.md) {
        return 404; 
    }
    location ^~ /.well-known/acme-challenge {
        allow all; 
        root /usr/share/nginx/html; 
    }
    if ( $uri ~ "^/\.well-known/.*\.(php|jsp|py|js|css|lua|ts|go|zip|tar\.gz|rar|7z|sql|bak)$" ) {
        return 403; 
    }
    location / {
        proxy_set_header Host $host; 
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; 
        proxy_set_header X-Forwarded-Host $server_name; 
        proxy_set_header X-Real-IP $remote_addr; 
        proxy_set_header X-Forwarded-Proto $scheme; 
        proxy_set_header Connection upgrade; 
        proxy_set_header Upgrade $http_upgrade; 
        proxy_http_version 1.1; 
        proxy_pass http://127.0.0.1:8081; 
    }
    http2 on; 
    if ($scheme = http) {
        return 301 https://$host$request_uri; 
    }
    ssl_certificate /www/sites/******/ssl/fullchain.pem; 
    ssl_certificate_key /www/sites/******/ssl/privkey.pem; 
    ssl_protocols TLSv1.3 TLSv1.2; 
    ssl_ciphers ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384:DHE-RSA-AES128-GCM-SHA256:ECDHE-RSA-AES256-SHA384:ECDHE-RSA-AES128-SHA256:!aNULL:!eNULL:!EXPORT:!DSS:!DES:!RC4:!3DES:!MD5:!PSK:!KRB5:!SRP:!CAMELLIA:!SEED; 
    ssl_prefer_server_ciphers off; 
    ssl_session_cache shared:SSL:10m; 
    ssl_session_timeout 10m; 
    error_page 497 https://$host$request_uri; 
    proxy_set_header X-Forwarded-Proto https; 
    add_header Strict-Transport-Security "max-age=31536000; includeSubDomains"; 
}

@Duso

[homelaeb]

I have the same problem. I deployed Trilium using Docker and then used Traefik as a reverse proxy. I found that the web version has issues, showing a message that the websocket has been disconnected.

[fengluo2]

Would it be convenient for you to share your proxy configuration?

[homelaeb]

My problem was solved. After I disabled uBlock Origin on the Trilium interface, the problem was resolved. The main issue was that the web interface showed a connection interrupted message, but the client did not have this prompt.

[eliandoran]

@homelaeb , is there a way you could find out which uBlock rule triggered and from which list? That way perhaps we could avoid issues like this in the future, say by renaming and endpoint.

[fengluo2]

It looks like someone else has the same problem.
@dosu

[dosubot[bot]]

Yes, this is a known issue with reverse proxy configurations. The key missing piece is likely the trustedReverseProxy setting in Trilium's config.ini:

[Network]
trustedReverseProxy=true

Or via environment variable: TRILIUM_NETWORK_TRUSTEDREVERSEPROXY=true

Without this, Trilium won't properly handle proxied WebSocket connections even if your Nginx config looks correct.

Additionally, make sure your proxy config includes proxy_cache_bypass $http_upgrade; and uses http:// (not https://) in proxy_pass to avoid WSS-to-WSS handshake issues.

For Traefik users (@homelaeb), the same principle applies—ensure the trusted reverse proxy setting is enabled and that WebSocket upgrade headers are being forwarded properly.

Full Nginx reference config is in the official docs.

To reply, just mention @dosu.

---

Share context across your team and agents. Try Dosu.

[fengluo2]

I tried the trustedReverseProxy configuration, but enabling it didn't help.