Most WebSocket failures on an Ubuntu VPS sit in one of four places: the client is using the wrong URL or scheme, NGINX is not forwarding the HTTP/1.1 upgrade, the proxy cannot reach the application, or an idle connection is being closed by a timeout. Fix them in that order. A correct NGINX tunnel needs HTTP/1.1 upstream, explicit Upgrade and Connection headers, a reachable backend, valid TLS for wss://, and a heartbeat policy for quiet connections.
Antihost offers Linux VPS plans with full root access, unlimited traffic on a 1 Gbps port and a 14-day free trial.
The procedure below applies to a conventional Ubuntu server running NGINX in front of a WebSocket-capable application such as Node.js, Python websockets, or websocketd. It does not cover Apache, Caddy, HAProxy, container ingress, CDN, or cloud-load-balancer-specific settings.
As an Amazon Associate I earn from qualifying purchases.
Understand what is failing before changing anything
A WebSocket connection begins as an HTTP/1.1 request. The client asks to switch protocols with Upgrade: websocket and a corresponding Connection: Upgrade header. If the server accepts, it returns HTTP 101 Switching Protocols and the connection becomes a WebSocket stream. NGINX describes this as a special tunnel mode: it is used when the client requests a protocol switch and the proxied server returns 101.
The Upgrade header is hop-by-hop. NGINX does not pass it to the upstream application automatically, so the reverse-proxy location must set it explicitly. NGINX also uses HTTP/1.0 to upstream servers by default; a WebSocket location must select HTTP/1.1 so the upgrade can complete.
#1 Best Overall
- BLUE LIGHT BLOCKING GLASSES: Our blue light glasses for women boast UV400 protection, blocking harmful blue rays from computer screens. With these bluelight glasses women, you can enjoy gaming, reading, or watching TV with no worries of eye strain.
- EYE RELIEF: Our blue light glasses are engineered to reduce blurry vision or strain caused by prolonged screen time. These womens blue light glasses aid in better sleep by preventing blue light from disrupting your natural sleep cycle, helping you fall asleep faster and enjoy a more restful night's sleep, making them the perfect christmas present.
- COMFORTABLE: Crafted from durable material, our trendy blue light glasses for woman or blue light glasses men ensure long-lasting comfort. The high-transmittance lenses accessories, gamer gifts for men, help keep your eyes relaxed. Perfect stocking stuffers, gifts for gamers men, christmas gifts for men, halloween costumes.
- LIGHTWEIGHT: These clear blue light glasses feature a lightweight frame, meaning they’ll stay comfy for long-term wear. Perfect as blue blockers glasses for women or mens blue light glasses, these non-prescription fake glasses for men can be worn throughout the day. The blue light blocking glasses women feature polycarbonate HD lenses, which are anti-reflective and restore true color.
- WORRY-FREE PURCHASE: If you experience any issues, our support team is ready to assist you quickly. These are the perfect costume glasses for cosplay dressing up.
That distinction explains the most useful symptoms:
| Observed result | Most likely layer | First checks |
|---|---|---|
| HTTP 400, HTTP 426, or an immediate close | Handshake, URL, headers, origin policy, or application logic | Exact path and query string, HTTP/1.1, forwarded upgrade headers, and the application’s handshake requirements |
| HTTP 502 or connection refused | NGINX cannot connect to the upstream | Service state, listening address, port, and the proxy_pass target |
| Connection succeeds, then closes after roughly 60 seconds of silence | Idle timeout | proxy_read_timeout and application ping or heartbeat traffic |
| TLS alert, certificate error, or wrong-version message | Public TLS or proxy-to-backend protocol mismatch | Certificate name, selected server block, and whether the upstream is HTTP or HTTPS |
Do not start by opening firewall ports or repeatedly changing NGINX directives. First establish whether the request reaches NGINX, whether NGINX can reach the application, and whether the application accepts the requested path.
Free tools Windows power users keep installed
One-click scans. No signup required.
Confirm the public endpoint and protocol
Check the URL character for character
Compare the URL used by the game client, browser, or WebSocket library with the location NGINX is configured to proxy. Verify the hostname, path, capitalization where the application treats paths as case-sensitive, and every query parameter. A location such as /socket/ will not necessarily serve a client pointed at /ws or at the site root.
Use ws:// only when the public endpoint is intentionally unencrypted. Use wss:// when the public listener is HTTPS. The certificate presented for wss:// must cover the hostname the client requests, and the request must land in the server block intended for that hostname.
Separate public and upstream schemes
The public connection and the proxy-to-application connection are independent. A public wss:// endpoint can proxy to an application that serves plain HTTP on a private port, provided NGINX is configured with the matching upstream protocol. Conversely, setting proxy_pass to HTTPS when the application speaks plain HTTP produces TLS or protocol errors between NGINX and the backend.
The Ubuntu websocketd documentation describes separate SSL mode and listen-port behavior. Apply the same principle to any WebSocket server: identify exactly which process terminates TLS and exactly which protocol the local listener serves.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Rank #2
- WINDEX GAMING WIPES: effortlessly clean all your gaming gear and gaming electronics in one easy step with our new Windex Gaming Wipes
- AMMONIA FREE: our ammonia-free formula is safe to use on all of your favorite gaming equipment like consoles, headsets, controllers, screens, keyboards, and more
- PRE-MOISTENED WIPES: each wipe instantly removes dust, dirt, and stubborn smudges and fingerprints leaving a streak-free shine
- ANTI-STATIC: great for cleaning and wiping down your gaming gear and electronics leaving behind no visible residue
- COMPACT RESEALABLE PACKAGE: store your pack of Windex Gaming Wipes anywhere in your home for whenever a quick and easy wipedown is needed
Use a WebSocket-capable NGINX location
Place the map directive in the http context, not inside a server or location block. Then use a location that matches the client path:
# in the http context
map $http_upgrade $connection_upgrade {
default upgrade;
'' close;
}
server {
listen 443 ssl;
server_name example.com;
location /socket/ {
proxy_pass http://127.0.0.1:3000;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $connection_upgrade;
proxy_read_timeout 300s;
}
}This is a pattern, not a complete certificate configuration. The HTTPS server still needs the certificate and key settings appropriate for your installation. Replace the hostname, path, port, and upstream scheme with the values your application actually uses.
What each directive does
map $http_upgrade $connection_upgrade: creates a value that isupgradewhen the client supplied an upgrade request andclosewhen it did not. This avoids sending an upgrade token on ordinary HTTP requests.proxy_http_version 1.1: selects HTTP/1.1 for the NGINX-to-application request. Without it, NGINX’s default upstream HTTP/1.0 behavior does not carry the WebSocket upgrade correctly.proxy_set_header Upgrade $http_upgrade: explicitly forwards the hop-by-hop upgrade request.proxy_set_header Connection $connection_upgrade: supplies the matching connection token expected by the upgrade handshake.proxy_pass: identifies the application address and protocol. A wrong port, address, or scheme causes an upstream failure even when the rest of the location is correct.proxy_read_timeout: controls how long NGINX waits for upstream data. It does not itself generate WebSocket heartbeats.
Validate the active configuration
- Edit the intended NGINX configuration file and save a backup of the previous working version.
- Run
sudo nginx -t. Do not reload if this reports a syntax or context error. - Run
sudo nginx -Tand inspect the expanded configuration. Confirm that the expected server name, location,proxy_pass, HTTP version, headers, and timeout are active, rather than hidden in a different included file or server block. - After a successful test, run
sudo systemctl reload nginx. A reload applies the configuration without stopping the master process.
If nginx -t says that map is not allowed in the current context, move it into the http block. If the configuration tests successfully but the request still reaches a different site, inspect server_name, the listen address, and the result of nginx -T for duplicate virtual hosts.
Verify the backend locally before investigating the Internet path
Test the application from the VPS itself. This removes DNS, TLS, browser, and external firewall variables from the first diagnostic step.
Crashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minuteWindows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstallsudo ss -ltnp | grep ':3000'
curl -i http://127.0.0.1:3000/health
sudo systemctl status your-websocket-service
sudo journalctl -u your-websocket-service -n 100 --no-pager
sudo tail -f /var/log/nginx/error.logInterpret the local checks
- If
ssshows no listener on the configured port, the application is stopped, crashed, listening on another port, or bound to another address. - If the health request returns a response, NGINX should be able to reach that address and port using the same protocol named in
proxy_pass. A health endpoint does not prove that the WebSocket path or handshake is correct, but it establishes basic reachability. - If the service status reports failure, read the recent journal entries before changing NGINX. Configuration files, environment variables, working directories, permissions, and application startup errors commonly prevent the listener from appearing.
- If NGINX’s error log reports connection refused or an upstream failure while the local listener check is empty, repair the service or its bind address first.
A backend bound only to an unexpected interface can also cause trouble. Keep the address in proxy_pass consistent with the address shown by ss. When NGINX and the application share the VPS, a local or private listener is generally safer than exposing the application port publicly.
Diagnose 400, 426, 502, and immediate disconnects
HTTP 400, HTTP 426, or an immediate close
These results usually mean that NGINX and the application are reachable but the upgrade request is unacceptable. Work through the handshake inputs:
Rank #3
- Ergonomic & Adjustable Design: Fight "text neck" and improve your posture. Designed for comfort, it offers an adjustable height (7.1in-8.5in) (1.4in adjustable range) and angle (5°-85°) Please note: cell phone stand is only 9 inches tall—the length of a standard pencil
- Without blocking subtitles Perfect for office desk Tiktok Face Time Zoom video—this is the ultimate kitchen desk essential for phones! Perfect viewing experience while reducing neck back strain, A must-have for gamers streamers desk, and anyone who values both style and support!
- Sleek & Stable Design fits Otterbox Case: Say goodbye to bent cables, tangles, and tip-overs! LISEN’s stylish adjustable desk phone holder features a built-in charging hole and smart cable management, keeping your phone secure and your workspace clutter-free cool gadgets for men
- ANTI-SLIP DESIGN free hands: The under 10.00 items easy gadgets back and the bottom of this kitchen essentials for women are fully covered by anti-skid silicone, which LISEN stand up desk decor can provide maximum protection device from any scratches and slides
- Your Perfect Viewing Companion:If your product arrives damaged or breaks within 365 days, reach out to LISEN for a quick and hassle-free solution. Struggling with assembly, like tightening the screw? We’ve got your back! Your experience matters to us. (Product including: phone Holder stand*1, screw*1, hexagon screwdriver*1, specification*1)
- Confirm that the client uses the exact path configured in the matching NGINX location.
- Confirm that the client uses
wss://for a public HTTPS listener andws://only for an intentionally unencrypted endpoint. - Confirm
proxy_http_version 1.1,Upgrade, andConnectionin the active configuration, not merely in an unused file. - Check the application’s origin policy and authentication or subprotocol requirements. A proxy can forward a valid upgrade while the application rejects the requested origin or handshake data.
- Read the application log at the exact time of the attempt. It may identify a wrong route, malformed query, missing credential, or deliberate close more precisely than NGINX does.
Do not treat a 400 as proof that the VPS network is broken. It is often a request-shape or application-handshake problem.
HTTP 502 or connection refused
A 502 generally means NGINX could not establish or maintain its connection to the configured upstream. Check that the service is running, listening on the expected port, reachable from the NGINX host, and serving the protocol named in proxy_pass. Correcting a timeout cannot fix a backend that is not listening.
The Tool Desk
Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →If the service restarts repeatedly, inspect journalctl and the application’s own logs for the first crash. A supervisor that restarts a failing process may make the symptom look intermittent: one request arrives while the process is up, and the next arrives during a restart.
Immediate close with no useful HTTP status
Capture the client’s connection result and compare its timestamp with both logs. An immediate close after a successful TCP or TLS connection can still be an application-level rejection. Check the path, origin, credentials, subprotocol, and whether the application expects a different first message after the upgrade.
Fix TLS and wss:// failures
For wss://, the client must complete TLS with the public NGINX listener before the WebSocket handshake is even attempted. Verify all of the following:
- The certificate covers the exact hostname in the client URL.
- The hostname selects the intended NGINX server block, including SNI-based selection.
- The certificate chain is installed as required by the client.
- The public listener is actually configured for SSL.
- The upstream scheme matches the application: use an HTTP upstream for a plain local listener and HTTPS only when the application itself serves TLS there.
A certificate problem is not repaired by adding WebSocket headers, and a backend protocol mismatch is not repaired by renewing the public certificate. Identify which TLS leg is failing before changing either side.
Recommended Free Tools
Rank #4
- Easy Installation: Our gaming lights have been designed to enhance your entertainment experience. Simply position the led light bar next to your TV or game console to create a game room environment with ease. They come with USB power and a 60 inch cord for direct mounting and mobility
- Audio Syncing & Extensive Mode: The built-in high-sensitivity music sensor allows you to sync the TV led lights to your favorite music. Lights react and move to the beat of music, film and game audio, creating an incredible immersive sound and light experience – and all without the need for an additional hub. You can choose from 64+ patterns, including strobe, illusion, jump, energy, gradient, running, chasing, fluttering mode etc. Each mode can be applied to different scenes
- 64+ Chasing IC+RGB & W Effect: The independent control design of IC+RGB and white all-in-one multifunctional rgbw led bar lights monitor backlight allows you to easily switch the led lights for desk between IC+RGB and white to enjoy a variety of lighting effects, you can choose white lighting mode with high brightness for better illumination when working, etc. Choose IC+RGB lighting mode when you need to create an entertaining atmosphere for the light show, 16 million colours of Color changing rgb light bar let you dance to the beat and create a dynamic party atmosphere
- Dynamic and Dimmable Lights: 1%-full brightness free brightness adjustment gives you the flexibility to adjust dimmable led light bar for room decorations or a variety of occasions
- USB Powered: USB light bars for room can be powered by powernank, usb charger, TV, Monitor, laptop PC mainframe, making behind TV led lighting bar easy to install in any location.TV led lights are powered by the TV usb interface / PC mainframe, can be turned on/off synchronously with TV / PC
Prevent disconnects caused by idle timeouts
NGINX documents a default proxy_read_timeout of 60 seconds when no data is received from the upstream. A connection that is healthy but silent can therefore close at about one minute. The example location uses 300s, but that is only an example; choose a value longer than the expected quiet period and consistent with every device and service between the client and VPS.
Pair the timeout with application heartbeats
Increasing NGINX’s timeout alone leaves the connection dependent on another network timer. Configure the WebSocket application to send protocol-level ping frames or other regular traffic at an interval safely below the shortest idle limit in the path. The client should answer pings according to the protocol library’s behavior, and the server should remove dead connections when pong responses stop.
Consider the complete route: client network, NAT, firewall, reverse proxy, load balancer, and any CDN or edge service. The shortest idle timer wins. A 300-second NGINX setting cannot keep a connection alive if another hop closes it after 60 seconds. Conversely, a heartbeat does not compensate for an incorrect upgrade or an unreachable backend.
Quick wins for a faster PC:
Clear out junk files and repair common Windows errorsFree Scan →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Repair Windows errors before they cause bigger problemsFix Now →Tell an idle timeout apart from a crash
Record when the disconnect occurs. A repeatable close near the same period, with no corresponding application crash, points toward an idle timer. A close that coincides with a process restart, out-of-memory event, deployment, or socket error points toward the application or host. Compare NGINX and application logs rather than relying on the client’s generic “disconnected” message.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Review Node.js server behavior when applicable
Node.js applications have their own HTTP server timeout and connection behavior. Review the version-appropriate HTTP API settings and application logs for header timeouts, socket errors, forced Connection: close, or code that destroys an apparently idle socket. These settings can create resets or premature closes even when NGINX is configured correctly.
Check that the process is creating a WebSocket server on the same HTTP server and port named in proxy_pass. If the application exposes a separate WebSocket path, route that path explicitly and keep the client URL aligned with it. Do not assume that an HTTP health endpoint and a WebSocket endpoint share the same route or handshake rules.
Best Value
- Compatible with Wide Screens - To ensure compatibility with the dual monitor mount, your each monitor must meet three conditions at the same time: First, computer screens size range: 13 to 32 inches. Second, screen weight range: 4.4 to 19.8 lbs. Third, the back of the monitor screen must have VESA mounting holes with a pitch of 75x75mm or 100x100mm.
- Regarding the compatibility with desks - Your desk must meet three conditions at the same time: First, desk material: Only wooden desks are recommended, plastic or glass desks cannot be used. Second, desk thickness range: 0.59" - 3.54". Third, the bottom of the desk should not have any cross beams or panels, as this will interfere with installation. We recommend carefully checking that your desk and monitors meets all above conditions before purchasing.
- Dual C-Clamp Hold - Worried your dual monitors might wobble or slip? Our upgraded base uses a larger platform plus a dual C-clamp structure to lock the dual monitor arm firmly to your desk. Each arm safely keeps your screens steady while you type, click and game—no shaking, no sliding, just a clean and secure setup you can trust every day. It also provides Grommet Mounting installation choice, both options ensure stable and secure fixation for your 0.59" - 3.54" desk.
- Full-Motion Adjustment For Comfortable View - Pull the screen closer when you’re deep in a spreadsheet, push it back to watch videos, or rotate to portrait for coding — moving everything smoothly with just one hand. The monitor stand offers +85°/-50° tilt, ±90° swivel and 360° rotation. Raise your monitor up to 15.75″ to support a healthy sitting posture. Whether you’re working from home, gaming through the night, or switching between video calls and documents, getting the screens to your natural line of sight helps relieve neck, shoulder and back strain so you can stay focused longer with less fatigue.
- Keep Your Desk Organized: By lifting both screens off the desktop, this dual monitor stand opens up valuable space for your keyboard, notebook, docking station or a simple, clutter-free work area. Built-in cable management guides wires along the arms, keeping cords out of sight and out of the way. Enjoy a tidy, modern workstation that looks as good as it feels to use.
Run the application under supervision
A WebSocket service should not depend on an interactive shell remaining open. Run it under systemd or the equivalent supervisor, configure restart-on-failure, and define the expected working directory and environment variables. The websocketd deployment model places the service behind NGINX and uses systemd for startup and restart handling.
What to verify in a supervised deployment
- The unit starts after the network is available and remains active after logout.
- The unit’s working directory contains the application files it expects.
- Environment variables used for the listen port, authentication, origin policy, and TLS mode are present in the service environment.
- Restart behavior is visible in the journal, rather than hiding a crash loop.
- NGINX’s upstream address and port match the service’s actual listener after every restart.
Keep the application on a local or private interface when NGINX is the public entry point. This reduces accidental exposure of a port that may not have the same TLS, authentication, rate limiting, or logging controls as the public endpoint.
Use a failure-isolation workflow
When several changes are possible, choose the one that matches the failure layer and the timing of the symptom. This prevents a broad configuration change from masking the original fault.
| Failure characteristic | Targeted action | Why it is the right scope |
|---|---|---|
| Handshake fails immediately for one path | Check URL, location match, upgrade headers, HTTP/1.1, and application handshake rules | These inputs determine whether the 101 upgrade can be accepted |
| Every proxied WebSocket path returns 502 | Check service state, bind address, port, and upstream scheme | The proxy is failing before application-level handshake logic |
| Only quiet sessions close | Set a suitable read timeout and add heartbeats | The connection works until no upstream data is received |
Only wss:// fails |
Check certificate coverage, SNI/server block, and TLS leg selection | Plain WebSocket and secure WebSocket use different public transport requirements |
| Connections fail after deployments or restarts | Inspect supervisor state, journal entries, environment, and working directory | The process lifecycle is interrupting otherwise valid connections |
Common mistakes that look like WebSocket bugs
Editing a file NGINX does not load
Ubuntu installations commonly include multiple configuration files. A perfect location in an unused file has no effect. Use sudo nginx -T to inspect the complete active configuration and verify the server block selected for the requested hostname.
Putting map in the wrong context
The upgrade map belongs in the http context. Keeping it inside a location causes a configuration-test error; replacing it with a hard-coded connection header can send an upgrade token on ordinary requests. The mapped value is safer when the same server block handles both regular HTTP and WebSocket traffic.
Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Fix the driver behind crashes, sound loss and screen glitches3Clear out junk files and repair common Windows errorsChanging the timeout to solve a handshake error
Timeouts affect waiting for upstream data after proxying. They do not add missing upgrade headers, correct a wrong URL, start a stopped service, or make a certificate valid. Fix the earliest failing layer first.
Opening the backend port publicly
Exposing the application port can hide the real proxy problem and creates a second public entry point. First prove that NGINX can reach a local or private listener. Expose only the endpoint that needs to be public, with TLS and the application’s intended access controls.
A complete recovery sequence
- Copy the exact client URL, including scheme, hostname, path, and query string.
- Decide whether the public endpoint is intentionally
ws://or must bewss://. Forwss://, verify certificate coverage and the selected server block. - Check the application locally with
ss, the health request,systemctl status, and the service journal. - Compare the listening address and port with
proxy_pass, and make sure the upstream protocol matches what the application serves. - Inspect the active NGINX configuration with
nginx -T. Confirm the matching location, HTTP/1.1, explicit upgrade headers, and a deliberate read timeout. - Run
sudo nginx -t, then reload withsudo systemctl reload nginxonly after the test succeeds. - Retry while watching the NGINX error log and application journal. Classify the result as handshake rejection, upstream failure, TLS failure, or idle disconnect.
- For an idle disconnect, set the timeout above the expected quiet period and implement ping traffic below the shortest timer anywhere in the route.
- For recurring process failures, repair the supervised service, its environment, working directory, or restart policy instead of repeatedly editing proxy directives.
This order keeps each change tied to a specific symptom. It also preserves a useful rollback point: if a change does not alter the observed failure layer, restore it and continue down the diagnostic path rather than stacking unrelated settings.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
