A blank page after logging into code-server with nginx usually stems from WebSocket upgrade failures or incorrect proxy headers. Verify that your reverse proxy configuration correctly forwards the Upgrade and Connection headers, as missing these prevents the client-side JavaScript from establishing the necessary real-time communication channel with the server instance.
Verify Nginx Proxy Headers
The most common cause for a white screen in this setup is an incomplete reverse proxy configuration. When code-server runs behind nginx, it relies on HTTP/1.1 upgrades to maintain persistent connections. If nginx strips the necessary headers, the browser receives the initial HTML but fails to load the application shell because the backend connection drops immediately.
You must ensure your location block includes specific directives for WebSocket support. The standard proxy_pass directive is insufficient on its own. You need to explicitly pass the Upgrade and Connection headers to tell nginx to switch protocols from HTTP to WebSocket when requested by the client.
Add the following lines inside your server block, specifically within the location context where you proxy to the code-server port (typically 8080 or 8443):
location / {
proxy_pass http://127.0.0.1:8080;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
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 $scheme;
}
The
proxy_http_version 1.1; line is critical because WebSockets require HTTP/1.1 or higher. Without it, nginx defaults to HTTP/1.0, which does not support the Upgrade mechanism. Similarly,
proxy_set_header Connection "upgrade"; ensures that the connection header is set to "upgrade" rather than "close", allowing the persistent tunnel to form.
If you are using a subdirectory path instead of a root path, such as
/code/, you must also adjust the proxy prefix. In that case, use
proxy_pass http://127.0.0.1:8080/code/; and ensure that the code-server instance itself is configured with the correct base URL prefix. Mismatched paths between nginx and code-server often result in 404 errors for static assets, which manifests as a blank page because the CSS and JS files fail to load.
Check Browser Developer Tools
When the page appears blank, do not rely solely on visual inspection. Open your browser's developer tools by pressing F12 or Ctrl+Shift+I. Navigate to the Console tab to look for red error messages. Common errors include
Failed to load resource: net::ERR_CONNECTION_REFUSED or
WebSocket connection failed.
These console errors confirm that the issue is network-related rather than a syntax error in your code. If you see CORS (Cross-Origin Resource Sharing) errors, it indicates that the browser is blocking requests due to mismatched origins. Ensure that the domain accessing code-server matches the
Host header being sent by nginx.
Inspect the Network tab as well. Look for requests to
/ws or similar WebSocket endpoints. If these requests show a status of 400 Bad Request or 502 Bad Gateway, your nginx configuration is likely rejecting the upgrade attempt. This reinforces the need to verify the
Upgrade and
Connection headers mentioned in the previous section.
Validate Code-Server Configuration
Beyond nginx, the code-server instance itself might be misconfigured. Check the systemd service file or the command-line arguments used to start code-server. Ensure that the
--bind-addr is set to
127.0.0.1:8080 if you are using localhost, or
0.0.0.0:8080 if you need external access without a proxy (though the latter is less secure).
If you are using authentication, verify that the password or token is being passed correctly. Sometimes, a blank page occurs if the session cookie is invalid or expired, causing the frontend to redirect to a login loop that fails silently. Clear your browser cookies for the domain and try logging in again.
Additionally, check the code-server logs for any startup errors. Use
journalctl -u code-server.service -f on Linux systems to view real-time logs. Look for messages indicating failed database migrations or permission issues with the workspace directory. These backend errors can sometimes prevent the API from responding correctly to the initial handshake.
Restart Services Properly
After modifying the nginx configuration, always test the syntax before reloading. Run
sudo nginx -t to validate your config file. If the test passes, reload nginx using
sudo systemctl reload nginx. Do not restart nginx unless necessary, as a reload preserves existing connections and minimizes downtime.
Similarly, restart the code-server service to apply any changes to its configuration. Use
sudo systemctl restart code-server@youruser, replacing
youruser with your actual Linux username. This ensures that the new settings are loaded into memory.
If the issue persists, consider checking for firewall rules that might be blocking WebSocket ports. While nginx handles the proxying internally, some cloud providers or local firewalls may interfere with long-lived connections. Ensure that port 80 or 443 is open and that no intermediate load balancers are stripping headers.
For more complex networking issues, such as those involving virtual networks or gateway configurations, you might find relevant troubleshooting steps in our guide on
Troubleshooting Weird Gateway Issue in VMware, although the core principles of header forwarding remain consistent across different environments.
Frequently Asked Questions
Why does code-server work locally but not behind nginx?
Local access bypasses the reverse proxy, so headers are handled directly by the browser and node process. Behind nginx, the proxy acts as an intermediary that must explicitly forward WebSocket upgrade headers; otherwise, the connection is terminated before the app loads.
Can I use HTTP/2 instead of HTTP/1.1 for code-server?
Yes, nginx supports HTTP/2, but WebSocket upgrades still require proper header handling regardless of the protocol version. Ensure that
proxy_http_version 1.1; remains in your config, as HTTP/2 multiplexing does not change the requirement for explicit Upgrade headers in the proxy pass.
What if I get a 502 Bad Gateway error?
A 502 error means nginx cannot connect to the upstream code-server process. Verify that code-server is running and listening on the expected port. Check the service status with
systemctl status code-server and ensure no other service is occupying port 8080.
Does disabling SSL affect the blank page issue?
SSL termination at nginx can introduce complexity if certificates are misconfigured. However, a blank page is primarily a WebSocket issue. If you disable SSL, ensure that
X-Forwarded-Proto is set to
http to prevent mixed content warnings that might block script execution.
How do I debug if the WebSocket connection fails?
Use browser developer tools to monitor the Network tab. Filter for WS (WebSocket) requests and inspect the response headers. If the upgrade fails, the response will typically be a 400 or 426 status code, indicating that the server refused the protocol switch due to missing headers.