Troubleshooting
Common issues and how to resolve them.
Upload fails with "Origin not allowed"
Symptom: A file upload or WebSocket connection attempt fails immediately with the message "Origin not allowed".
Cause: The SkySend server automatically allows the origin that matches BASE_URL. If the frontend is accessed from a different URL - for example a different port, hostname, or protocol - the server rejects the WebSocket connection because that origin is not in the allowed list.
This typically happens in development or when BASE_URL is set to a different address than the one the browser is using to access the app.
Fix: Make sure BASE_URL matches the URL you are using in the browser exactly, including the protocol and port:
BASE_URL=https://send.example.comIf you need to allow additional origins on top of BASE_URL (for example when the frontend is served from a CDN at a different domain), add them as a comma-separated list in CORS_ORIGINS:
CORS_ORIGINS=https://cdn.example.com,https://www.example.comSee the Environment Variables reference for details.
crypto.subtle is undefined / Cannot read properties of undefined (reading 'importKey')
Symptom: Uploading a file or creating a note fails with one of these errors in the browser console:
- Firefox:
can't access property "importKey", crypto.subtle is undefined - Chrome / Edge:
Cannot read properties of undefined (reading 'importKey')
Cause: SkySend uses the Web Crypto API (crypto.subtle) to perform client-side encryption. Browsers only expose this API in secure contexts - meaning the page must be served over HTTPS or from localhost. Plain HTTP URLs (e.g. http://192.168.1.10:3000 or http://server:3000) are not considered secure and the API is unavailable.
Fix: Place SkySend behind a reverse proxy that terminates TLS. See the Reverse Proxy guide for setup examples with Caddy, Nginx, and Traefik.
Local testing
If you are only testing locally on the same machine, http://localhost:3000 works without HTTPS because localhost is treated as a secure context by browsers.
Chrome asks where to save every download
Symptom: In Chrome, Edge or Brave, each download opens a save dialog before it starts instead of going straight to the downloads. Under Technical info on the download page, Method reads "Save File Picker" instead of "SW Stream", and the browser console shows:
[SkySend] SW registration failed: SecurityError: Failed to register a ServiceWorker ... An SSL certificate error occurred when fetching the script.Cause: The instance runs on HTTPS with a certificate the browser does not trust, usually a self-signed one whose warning was clicked away. Encryption still works, because an https:// page counts as a secure context. Chromium-based browsers refuse to register a Service Worker from such an origin, so SkySend cannot stream the download through it and falls back to the save dialog. Download Modes describes both paths.
Fix: Serve SkySend with a certificate the browser trusts. Caddy gets one from Let's Encrypt by itself, see the Reverse Proxy guide. For an instance that is only reachable inside your network, add the certificate authority that signed its certificate to the trust store of the devices that use it. Clicking through the browser warning is not enough.
Upload silently fails or hangs with Nginx
Symptom: File uploads stall, disconnect mid-way, or the progress bar freezes.
Cause: Nginx's default request buffering interferes with SkySend's streaming upload transport. Missing or incorrect WebSocket headers also break the WebSocket upload mode.
Fix: Make sure your Nginx config includes all required directives. See the Reverse Proxy guide for the full reference config, in particular:
proxy_request_buffering off- required for streaming uploadsUpgrade/Connectionheaders and the$connection_upgrademap - required for WebSocket uploadsproxy_read_timeout/proxy_send_timeout- must exceed the longest expected upload durationclient_max_body_size- must be at least as large as yourFILE_MAX_SIZEsetting
Downloads behind Nginx are sometimes slow
Symptom: Most downloads run at full speed, but some crawl at a small part of it for no visible reason, in the browser and in the CLI alike. Uploads are not affected.
Cause: The Nginx config has proxy_buffering off, which older versions of this guide recommended. Nginx then reads the download from SkySend into a single buffer of a few kilobytes, and on the local connection between the two that can leave the TCP window shut for seconds at a time.
Fix: Replace proxy_buffering off; with these two lines and reload Nginx:
proxy_buffering on;
proxy_max_temp_file_size 0;The second line keeps Nginx from writing downloads to temporary files. See the Reverse Proxy guide for the full config.
S3 downloads fail with CORS error
Symptom: A download stalls immediately after clicking the download button and shows the error: "S3 CORS error: The bucket must allow cross-origin GET requests from this origin."
Cause: SkySend uses presigned URLs for S3/R2 downloads so the file stream goes directly from the bucket to the browser without passing through SkySend. The browser enforces CORS for these cross-origin requests, so the bucket must explicitly allow GET requests from SkySend's origin.
Fix: Open your bucket's CORS settings and add a rule that allows GET and HEAD requests from your SkySend origin:
[
{
"AllowedOrigins": ["https://send.example.com"],
"AllowedMethods": ["GET", "HEAD"],
"AllowedHeaders": ["*"],
"MaxAgeSeconds": 3600
}
]For Cloudflare R2, set the allowed origin in the R2 bucket settings under CORS policy.
No trailing slash
The origin value must not end with a slash. https://send.example.com is correct. https://send.example.com/ will not match and CORS will still fail.
Share link opens but the page says "not found"
Symptom: A share link that works when opened directly shows "not found" after being sent by email. The address bar contains %23 where the link should have a #:
https://send.example.com/file/c9c9c3a2-...-8b001a8051c7%23Xy1wbZmb0OePQ...Cause: A mail security gateway rewrote the link. Microsoft Defender for Office 365 Safe Links wraps the original URL in a query parameter, and the # survives that round trip only as its percent-encoded form %23. Browsers never decode %23 in a path, so the key ends up as part of the path instead of the URL fragment, and the page cannot read it.
Proofpoint URL Defense, Mimecast, and similar products rewrite links the same way. Some of them drop the fragment entirely.
Fix: Nothing to configure. SkySend detects this exact shape and moves the key back into the fragment before the page loads, so the link works on the second hop. A warning is shown because the rewrite has a real consequence: the key travelled to the server inside the request path, which a normal share link never does.
The key was exposed
A rewritten link is no longer a zero-knowledge link. The server, the reverse proxy, and any CDN in front of them saw the key in the request path. SkySend truncates its own request log at the resource ID, but logs outside the application are the operator's responsibility.
Asking for a new link does not help, because the old key is already out. What helps is removing what that key unlocks: download or view the content, then ask the sender to delete the upload. Once the ciphertext is gone, a key sitting in a log line is worthless. A one-time download link that has already been used is deleted for you.
This is not airtight. On an upload without a password, an operator who keeps the access log alongside backups of the database and the blob storage holds everything needed to decrypt it, deletion included. On an upload with a password, they do not: the password never reaches the server, and without it the leaked secret decrypts nothing.
So treat a rewritten link as compromised. Re-share genuinely sensitive content through a different channel, with a password sent separately. See the Threat Model for the full breakdown.
If the gateway strips the fragment instead of encoding it, nothing can recover the key, because it never reaches the browser. Share the link through a different channel in that case.