[Bug]: Stirling PDF on Mac OS cant connect to self-hosted server

[Mr-Boshi]

Installation Method

Docker

The Problem

The desktop app shows "Could not connect to server" when I try to connect it to a self-hosted account. The webUI is accessible on the URL i am pasting to the Server URL field. Web version of the app works fine.

The reverse proxy config for NGINX is taken from the docs, no changes except the certs paths and the host\server addresses were made.

How do I troubleshoot this issue? The message is not very informative.

Version of Stirling-PDF

2.1.4

Last Working Version of Stirling-PDF

No response

Page Where the Problem Occurred

No response

Docker Configuration

The config is default with these env vars set:
- env:
            - name: LANGS
              value: en_GB,en_US,ar_AR,de_DE,fr_FR,es_ES,zh_CN,zh_TW,ca_CA,it_IT,sv_SE,pl_PL,ro_RO,ko_KR,pt_BR,ru_RU,el_GR,hi_IN,hu_HU,tr_TR,id_ID
            - name: SECURITY_ENABLELOGIN
              value: "true"
            - name: SYSTEM_DEFAULTLOCALE
              value: ru-RU
            - name: SYSTEM_ENABLEANALYTICS
              value: "false"
            - name: UI_APPNAME
              value: Boshi's Stirling-PDF
            - name: METRICS_ENABLED
              value: "false"
            - name: SYSTEM_FRONTENDURL
              value: https://redacted.pw/
            - name: SYSTEM_CORSALLOWEDORIGINS
              value: https://redacted.pw/
            - name: DISABLE_ADDITIONAL_FEATURES
              value: "false"
            - name: VITE_API_BASE_URL
              value: https://redacted.pw/
            - name: SYSTEM_ROOTURIPATH
              value: /
            - name: SECURITY_CSRFDISABLED
              value: "false"
            - name: MAIL_ENABLED
              value: "true"
            - name: MAIL_ENABLEINVITES
              value: "true"
image: stirlingtools/stirling-pdf:latest@sha256:940c83732d373b08efd110de708d51d639705404de7dabc7230e5665819efb4a

Relevant Log Output

Additional Information

No response

Browsers Affected

No response

No Duplicate of the Issue

• I have verified that there are no existing issues raised related to my problem.

[dosubot]

Hi @Mr-Boshi! I'm Dosu and I’m helping the Stirling-PDF team.

This is a common issue with the Stirling PDF desktop app when connecting to a self-hosted server via Docker, especially with login enabled and a reverse proxy in place. Here are the most effective troubleshooting steps:

1. Double-check that the URL you enter in the desktop app (including protocol and port) matches exactly what works in your browser. If you use HTTPS in the browser, use the same in the app. The desktop app supports custom ports (e.g., https://yourdomain:443), but mismatches can cause connection failures example.

2. If you use a self-signed SSL certificate, make sure it is trusted by Mac OS. Add it to your keychain and restart the app, as untrusted certs will cause silent connection failures.

3. The desktop app expects the server’s /api/v1/info/status endpoint to be reachable. Try accessing this endpoint from your Mac using curl or a browser to confirm network and reverse proxy routing are correct example.

4. Check the desktop app logs at /Users/<your-username>/Library/Application Support/Stirling-PDF/logs. Launching the app from the command line may also reveal errors not shown in the GUI example.

5. Review your NGINX access and error logs for failed requests or SSL errors when the desktop app tries to connect.

6. If you have a Web Application Firewall (WAF) or extra NGINX security modules enabled, try disabling them temporarily. Some users have found that WAFs block requests from the desktop app even when the web UI works example.

7. There is a known issue where the desktop app cannot connect if SECURITY_ENABLELOGIN is set to true in Docker, even though the web UI works. As a test, set SECURITY_ENABLELOGIN=false and restart the container. If the desktop app connects, the problem is with authentication/session handling in the desktop app example. Note: this disables login security for all users.

8. If you change login settings or update the app, clear the desktop app cache or reinstall it to avoid stale authentication state example.

If you need login security, the web UI is currently more reliable for authenticated access. The maintainers are aware of these desktop app limitations and are working on improvements, but authentication bugs with Docker/reverse proxy setups are still reported in recent versions example.

If you find any specific error messages in the logs or NGINX output, feel free to share them for more targeted help.

To reply, just mention @dosu.

---

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