iOS/iPadOS file upload fails behind Nginx reverse proxy

[mastro35]

What went wrong?

I am experiencing an issue with file uploads from iOS/iPadOS when Grimmory is accessed through an Nginx reverse proxy.

The upload works correctly when accessing Grimmory directly on its exposed port, but fails when going through Nginx.

The issue appears to be specific to iOS/iPadOS clients. The same upload works correctly from macOS.

Behavior

The request reaches Grimmory, but the backend reports that the multipart file part is missing:

Required part 'file' is not present.

org.springframework.web.multipart.support.MissingServletRequestPartException:
Required part 'file' is not present.

The failing request:

POST /api/v1/files/upload

returns:

HTTP 500

Nginx configuration

Nginx is configured as a standard reverse proxy:

location / {
    proxy_pass http://127.0.0.1:6060;
    proxy_http_version 1.1;

    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 https;

    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection $connection_upgrade;

    client_max_body_size 200M;

    proxy_buffering off;
    proxy_cache off;

    proxy_read_timeout 86400;
    proxy_send_timeout 86400;
}

I also tested with different proxy settings:

• proxy_request_buffering off
• proxy_request_buffering on
• WebSocket headers enabled/disabled
• Cloudflare proxy disabled

The issue remains only on iOS/iPadOS behind Nginx.

Additional information

The Nginx access log shows:

POST /api/v1/files/upload HTTP/1.1 500

The request has:

Content-Type: multipart/form-data; boundary=...

but Spring Boot reports that the file multipart part is missing.

Expected behavior

Uploading files from iOS/iPadOS should work the same way whether Grimmory is accessed directly or through a reverse proxy.

Question

Could this be related to the way the frontend handles multipart uploads on iOS/iPadOS when running behind a reverse proxy?

Are there any known requirements or additional proxy headers/configuration needed for Nginx deployments?

How can we reproduce it?

Reproduction

1. Accessing Grimmory directly:

https://<raspberry-ip>:6060

2. Uploading a file from iPadOS works correctly.

3. Accessing Grimmory through Nginx:

https://books.example.com

4. Uploading the same file from iPadOS fails.

The same upload through the Nginx URL works correctly from macOS Safari.

What Build of Grimmory are you on?

Stable

Your setup

Environment

• Grimmory version: 3.2.4

• Deployment: Docker

• Backend: Spring Boot

• Reverse proxy: Nginx 1.22.1

• Client:

  • iPadOS Safari: affected
  • macOS Safari: works correctly

Screenshots or error messages (optional)

No response

Before submitting

• I've searched existing issues and discussions and this hasn't been reported yet
• I've reviewed this report and have completed it as fully as I can

[imnotjames]

This sounds like it's not a bug in Grimmory, but in your configuration. I'm going to move this to a discussion.

[mastro35]

I'm not so sure about that, the configuration is super simple, just a nginx reverse proxy barely configured that just forward the requests to the backend on the 6060 port and a standard 3.2.4 docker container with grimmory.

The fact that everything works if I use MacOS instead of iOS suggests me that there must be something wrong on the frontend side when the client is a mobile safari application (not sure if the proble is with safari or with the iPhone's file picker tough).

Has anyone else tried this kind of configuration on a super recent grimmory version? (I'm quite sure that with older releases everything was working fine).

[rakeshutekar]

The giveaway is that it works direct and from macOS, but fails through Nginx from iOS/iPadOS — with the body arriving but the multipart file part missing (Required part 'file' is not present). That combination almost always comes down to how Nginx proxies the request to the backend, specifically Expect: 100-continue and the proxy HTTP version.

iOS/iPadOS uploads send Expect: 100-continue and hold the request body until they get a 100 Continue. Nginx proxies to upstreams with HTTP/1.0 by default (proxy_http_version 1.0), which doesn't handle Expect: 100-continue — so the client never gets the go-ahead, the body is sent in a way the backend can't reassemble, and Spring ends up parsing a request with no file part. macOS/desktop clients typically don't send Expect: 100-continue the same way, which is why they slip through. Same reason it works hitting the port directly (no proxy in the path).

The fix is to make Nginx speak HTTP/1.1 to the backend and stop forwarding the Expect header:

location /api/v1/files/upload {   # or your general proxy location
    proxy_http_version 1.1;
    proxy_set_header Connection "";
    proxy_set_header Expect "";        # let Nginx buffer & forward the body itself
    proxy_request_buffering on;        # default; ensures a clean Content-Length to the backend

    client_max_body_size 100m;         # size to your largest upload; a too-small limit is the other classic cause

    proxy_pass http://grimmory_backend;
}

Two things to double-check while you're in there, since they cause the same "part not present" symptom:

• Don't let anything rewrite Content-Type. The multipart boundary lives in that header; if a proxy_set_header Content-Type ... (or a more_set_headers) is clobbering it, the backend can't find the boundary and the file part vanishes. Leave the client's Content-Type untouched.
• client_max_body_size — if the iOS file is larger than the limit, Nginx can cut the body off mid-stream; you'd sometimes see 413, but with buffering it can also surface downstream as a missing part. Set it comfortably above your max upload.

Start with proxy_http_version 1.1; + clearing Expect — that's the specific difference between the iOS path and the macOS/direct paths, and it's the most common fix for "uploads work everywhere except iOS behind Nginx." If it still fails after that, grab POST access logs on both Nginx and the backend and compare the Content-Type and Content-Length/Transfer-Encoding the backend actually receives vs. what iOS sent.

[iplux]

hello
i have the same issue behind a cloud flare tunnel and it was working some months ago. no problems using a mac browser but it gives the same error as in the original discussion if used by a ios browser

[rakeshutekar]

You did the hard part here, and your evidence actually rules out what I said earlier — apologies, the Expect: 100-continue theory was wrong. Your logs settle it: Expect:"-" (no 100-continue), ReqLen:864 (headers only), Content-Length: 0 forwarded, and curl to the exact same URL succeeding. The body leaves the iPhone empty; Nginx is just faithfully forwarding an empty body. So it's client-side, exactly as you concluded.

But it's not quite "Safari's FormData is broken" in general — the decisive clue is the one you almost dismissed: same device, same build, works on https://<ip>:6060, fails on https://books.mastro35.com. Only one thing meaningfully differs between those two URLs, and it's not Nginx: whether Grimmory's Service Worker is active.

Grimmory is an Angular PWA and registers a service worker — you can see it in the repo:

• frontend/src/main.ts: provideServiceWorker('ngsw-worker.js', { registrationStrategy: 'registerWhenStable:30000' })
• frontend/ngsw-config.json with scope /

A service worker only registers on a valid-certificate HTTPS origin (a real secure context). So:

• https://books.mastro35.com (Let's Encrypt cert) → the SW registers and controls the page.
• https://<raspberry-ip>:6060 (self-signed cert) → Safari refuses to register the SW, so uploads go out normally. That's why direct works.
• curl → no service worker → works.

And the last piece — why macOS is fine even though it also has the SW on that domain — is that this is an iOS WebKit bug specifically: when a service worker controls the page, iOS Safari drops the File part of a multipart upload body (it's a long-standing WebKit issue with file bodies passing through the SW request pipeline — e.g. webkit.org/b/187461). So the request goes out with the correct multipart/form-data; boundary=… header but zero body — precisely your Content-Length: 0. macOS WebKit doesn't hit it; iOS does.

That also fits @iplux's Cloudflare-tunnel report (valid cert → SW active → same bug) and the "worked months ago" observation (this tends to appear when the PWA/service worker gets added or an iOS/WebKit version regresses).

Quick way to confirm before anyone changes code: the SW registers registerWhenStable:30000, i.e. ~30s after load. Hard-reload the site on the iPhone and try an upload within the first few seconds — if an immediate upload succeeds but one a minute later fails, that's the service worker taking control. (On desktop you'd just Unregister it in Web Inspector; iOS makes that harder, hence the timing trick.)

On the fix — this is a Grimmory frontend issue, not an Nginx/config one, so there's unfortunately no proxy setting that'll fix it. For a proper fix (cc @imnotjames), the upload needs to avoid routing the File through the SW-controlled request on WebKit — the usual approaches are to POST the raw file as the request body (application/octet-stream) instead of wrapping it in FormData, or to serve the upload endpoint from a path/scope the service worker doesn't control. For you as a self-hoster right now, there's no clean workaround short of uploading from a desktop browser until it's patched — nginx tuning (including my earlier suggestions) won't move it.

Happy to help turn this into a frontend issue with the above if it's useful — it's a clean repro now that you've isolated the empty body.

[mastro35]

Hi @rakesh,

Thank you so much for the brilliant analysis and for taking the time to explain the root cause in such detail. Really appreciate your help!

Since I needed a temporary workaround for iOS without sacrificing HTTPS security (or waiting for a frontend patch), I implemented a quick Nginx rule to block the Service Worker from registering altogether.

For anyone else hitting this issue on self-hosted instances, adding this block inside the server { listen 443 ssl; ... } context in Nginx prevents the SW from taking control while keeping the connection fully secure over HTTPS:

location = /ngsw-worker.js {
return 404;
}

After reloading Nginx and clearing site data on iOS Safari to purge the previously installed Service Worker, FormData multipart uploads work perfectly on iOS again.

I don’t know if this mess up something else, I will keep an eye on the next few days. :)

thanks again
D.

@imnotjames do you think I have to open another issue to ask for a patch or you can move this conversation back to the issue page?

[bgarret]

@mastro35 Thanks for the workaround, this was annoying 😠 @imnotjames the root cause is in grimmory, can we move this back to an issue ?

[imnotjames]

The root cause is not in Grimmory but in Safari and its lack of regularly integrating fixes for chromium bugs.

A workaround in Grimmory may be possible.

I have been unavailable for several days from an unusually busy work week. I do have my eye on this and have been investigating it.

I do not agree with the suggestion that we should bypass the service worker - that defeats the purpose.

However, there may be other mitigations.

Yes, it will be moved back over now that it has been shown to be a bug - however, one which I am unable to reproduce.

[mastro35]

Hi @rakesh,
thanks for your message!

Here's my nginx configuration with your suggestions:

~ $ cat /etc/nginx/sites-available/books.mastro35.com 
map $http_upgrade $connection_upgrade {
    default upgrade;
    ''      "";
}

log_format ios_debug '$remote_addr - [$time_local] "$request" '
                     'Status:$status BytesSent:$body_bytes_sent '
                     'ReqLen:$request_length '
                     'ContentType:"$http_content_type" '
                     'Expect:"$http_expect"';

server {
    listen 443 ssl;
    server_name books.mastro35.com;

    # Certificati SSL
    ssl_certificate /etc/letsencrypt/live/books.mastro35.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/books.mastro35.com/privkey.pem;
    include /etc/letsencrypt/options-ssl-nginx.conf;
    ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem;

    # Limite dimensioni file upload
    client_max_body_size 200M;
    client_body_timeout 600s;

    location / {
        proxy_pass http://127.0.0.1:6060;

        # Requisiti HTTP/1.1 e gestione Expect (Fix iOS)
        proxy_http_version 1.1;
        proxy_set_header Expect "";
        proxy_request_buffering on;

        # Gestione WebSocket e Keep-Alive
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;

        # Header standard per Spring Boot
        proxy_set_header Host $http_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;
        proxy_set_header X-Forwarded-Ssl on;
        proxy_set_header X-Forwarded-Port $server_port;

        # Timeout estesi per upload grandi
        proxy_read_timeout 600s;
        proxy_send_timeout 600s;

	access_log /var/log/nginx/ios_upload.log ios_debug;
    }
}

# Redirect HTTP -> HTTPS
server {
    listen 80;
    server_name books.mastro35.com;

    return 301 https://$host$request_uri;
}

Now, I am bypassing Cloudflare completely (the record is DNS only now) and running the test directly against Nginx over a clean connection. Here are the raw logs captured at both Nginx and local TCP level (tcpdump to Spring Boot):

1. Nginx Entry Log (Direct client connection)
   Plaintext <CLIENT_IP> - [05/Aug/2026:07:53:38 +0200] "POST /api/v1/files/upload HTTP/1.1" Status:500 BytesSent:134 ReqLen:864 ContentType:"multipart/form-data; boundary=----WebKitFormBoundarypAckOlpPAA1NAoeB" Expect:"-"
2. Backend tcpdump on Port 6060 (Nginx -> Spring Boot)
   HTTP POST /api/v1/files/upload HTTP/1.1 Connection: close Host: books.mastro35.com X-Real-IP: <CLIENT_IP> X-Forwarded-For: <CLIENT_IP> X-Forwarded-Proto: https X-Forwarded-Ssl: on X-Forwarded-Port: 443 Content-Length: 0 Accept: application/json, text/plain, */* Content-Type: multipart/form-data; boundary=----WebKitFormBoundarypAckOlpPAA1NAoeB Origin: https://books.mastro35.com Sec-Fetch-Site: same-origin Sec-Fetch-Mode: cors User-Agent: Mozilla/5.0 (iPhone; CPU iPhone OS 18_7 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/26.6 Mobile/15E148 Safari/604.1 Authorization: Bearer eyJhbGciOi...

Direct Connection Takeaways:

Expect: 100-continue is absent: Expect:"-" in Nginx logs confirms iOS Safari is not sending a 100-continue header for this request.
Body arrives empty at Nginx: Total incoming request size (ReqLen) at Nginx is only 864 bytes (headers only).
Content-Length: 0 is forwarded: Nginx passes Content-Length: 0 downstream because no binary body bytes were transmitted by the client over the wire.
curl direct test: Running a curl multipart upload to the exact same HTTPS URL succeeds with HTTP 204.

This should confirm Nginx is proxying the request transparently. The issue appears to originate directly in the web app execution under WebKit/Safari iOS, where appending the file object to FormData fails to attach/read the underlying binary stream, causing Safari to dispatch an empty request body (Content-Length: 0).