What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
When nginx -t fails after you add HTTPS, the final line—configuration file ... test failed—is only a summary. The useful diagnosis is usually the earlier message naming a certificate, key, include file, permission, or upstream connection. Correct that specific condition, run the test again, and reload NGINX only after it reports a successful syntax and file check.
Antihost offers Linux VPS plans with full root access, unlimited traffic on a 1 Gbps port and a 14-day free trial.
This guide shows how to test the complete effective configuration, repair the common SSL and upstream-TLS failures, and choose a safe TLS-termination design when Varnish is also in the request path.
As an Amazon Associate I earn from qualifying purchases.
What nginx -t actually checks
The -t option does more than parse punctuation. NGINX checks the configuration syntax and then attempts to open files referenced by that configuration. That includes certificate files, private keys, access and error-log paths, maps, included snippets, and other resources required while the configuration is loaded.
Use the test from the same installation and account context that owns the running service. A common sequence is:
#1 Best Overall
sudo nginx -tA successful result normally ends with messages equivalent to “syntax is ok” and “test is successful.” A failure may print several lines; always start with the first specific error and treat the final “configuration file … test failed” line as the status, not the cause.
See the complete expanded configuration
When an individual file looks correct but NGINX still rejects the setup, run:
sudo nginx -TThe -T option performs the test and dumps the fully expanded configuration, including files pulled in by include directives. This reveals which server block is actually handling port 443, whether a later include overrides a setting, and whether an old certificate path is still active elsewhere.
A disciplined error-fixing workflow
- Run the test and save the complete output. Use
sudo nginx -t; do not diagnose from only the last line. - Read the named path and line number. Open that exact file and inspect the directive at the reported line. If the path belongs to an included snippet, use
nginx -Tto see where it enters the effective configuration. - Check spelling and path resolution. Certificate paths are absolute in production configurations for a reason. Confirm that every directory component exists and that symbolic links point to the intended current file.
- Check readability under the service’s security model. The NGINX master process must be able to read the private key and certificate. File ownership, mode bits, SELinux or AppArmor confinement, and parent-directory traversal permissions can all block access even when a shell user can open the file.
- Validate the file format and relationship. Certificates and keys must be valid PEM files, and the private key must match the certificate. A correctly spelled path does not make malformed contents usable.
- Check the complete HTTPS server block. An HTTPS listener needs a certificate and key in the effective server configuration, not merely in a file that is never included.
- Retest before changing the running service. Run
sudo nginx -tafter each correction. Only a successful test should be followed by a graceful reload.
Repairing HTTPS server-block errors
Missing ssl_certificate
The error no "ssl_certificate" is defined means an HTTPS listener is active without a certificate directive in the server configuration NGINX selected. Check every server block containing listen 443 ssl;, including blocks loaded through nested includes. A minimal arrangement has all three elements together:
server {
listen 443 ssl;
server_name example.com;
ssl_certificate /etc/nginx/tls/example.com/fullchain.pem;
ssl_certificate_key /etc/nginx/tls/example.com/privkey.pem;
location / {
proxy_pass http://app_backend;
}
}If multiple names share one address, verify the intended default server and SNI behavior. Adding a certificate to an unrelated server block will not fix the block that owns the failing 443 listener.
Rank #2
cannot load certificate
This message covers several distinct faults:
- The path is wrong, the file was moved, or a renewal changed a symlink target.
- The NGINX master process cannot traverse a directory or read the file.
- The file is not PEM-encoded or contains damaged text.
- The certificate and private key do not form a pair.
Keep the public certificate (often a full-chain file) readable by the service, but restrict the private key to the minimum ownership and mode required by your deployment. Do not solve a permission problem by making the key world-readable. If a certificate authority supplied separate intermediate certificates, place them in the chain order expected by NGINX: the server certificate first, followed by its intermediate certificate or certificates. An incorrect chain order can prevent NGINX from starting.
BIO_new_file() failed
BIO_new_file() failed indicates that NGINX could not open a referenced file. Confirm the exact path in the error, then inspect both the file and every parent directory. Typical checks include:
sudo ls -l /etc/nginx/tls/example.com/fullchain.pem
sudo namei -l /etc/nginx/tls/example.com/fullchain.pemThe second command helps expose a directory lacking execute (traverse) permission. If traditional permissions look correct, review SELinux or AppArmor denials and the service’s systemd sandboxing settings.
PEM_read_bio_X509_AUX() failed
This error points to invalid certificate contents or PEM formatting. Open the file and confirm it contains an intact block beginning with -----BEGIN CERTIFICATE----- and ending with -----END CERTIFICATE-----, with no accidental binary data or truncated lines. Check the private key separately; a certificate block pasted into the key file, or a key encrypted with a passphrase that the unattended service cannot supply, will fail at startup.
Confirm that the key matches the certificate
A certificate can be valid while belonging to a different private key. Compare the public-key digest derived from each file with an appropriate OpenSSL command for your key type, or use your certificate-management system’s built-in match check. The important result is that the certificate’s public key and the configured private key are the same pair; hostname validity alone does not prove that.
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 →TLS versions and cipher settings
For new configurations, follow current NGINX guidance and allow TLS 1.2 and TLS 1.3 unless a documented compatibility requirement says otherwise. Do not copy obsolete SSLv3 or weak cipher examples into a modern server. A protocol setting normally does not cause a syntax error by itself, but an outdated directive or unsupported option can stop NGINX from loading on a newer or older build. Check the version-specific documentation shipped with your NGINX package before adding advanced TLS directives.
Separate configuration parsing from client compatibility testing. Once nginx -t succeeds, make a local HTTPS request to the intended listener and inspect the negotiated protocol, certificate name, and response status. A browser warning may indicate a chain or hostname problem even though NGINX accepted the files.
When NGINX proxies to an HTTPS upstream
There are two TLS connections to reason about: the public client-to-edge connection and the NGINX-to-upstream connection. A certificate that is correct for clients does not automatically satisfy validation of an HTTPS backend.
Use the right upstream scheme
If the application server speaks HTTPS, the proxy target must use an https:// URL:
Recommended Free Tools
location / {
proxy_pass https://app_backend;
}Using http:// against a TLS port produces protocol errors; using https:// against a plain HTTP port produces a failed handshake.
Configure trust, SNI, and verification deliberately
For a verified upstream connection, NGINX needs a trusted CA file containing the issuer chain for the backend certificate, plus verification enabled at the level appropriate to your release and policy. If the backend selects its certificate by server name, send the expected SNI name with the proxy TLS settings. Also check whether the upstream requires a client certificate (mutual TLS); in that case NGINX needs its own client certificate and key in addition to the CA used to verify the server.
An upstream SSL handshake failed message should therefore be investigated in this order:
- Confirm the backend port actually speaks TLS.
- Confirm the protocol versions overlap between NGINX and the backend.
- Set the correct SNI/server name when the backend hosts multiple names.
- Verify that the configured CA trusts the backend certificate and that its name matches the requested server name.
- Determine whether the backend expects a client certificate.
Disabling verification can hide a trust-chain problem, but it removes authentication of the backend. Treat that as a narrowly scoped temporary diagnostic, not a default production fix.
Choosing where TLS terminates with Varnish
TLS termination is an architectural decision, not merely an NGINX syntax change. The edge component that accepts the public HTTPS connection owns the public certificate and decrypts client traffic. A separate hop may then be encrypted again with a private upstream certificate.
| Design | Public TLS endpoint | Backend hop | Operational characteristics |
|---|---|---|---|
| NGINX terminates TLS | NGINX on port 443 | HTTP or HTTPS to Varnish/application | NGINX owns certificate loading and reload testing; proxy settings determine whether the next hop is encrypted. |
| Varnish terminates TLS | Varnish native HTTPS listener | HTTP or HTTPS to the backend | Certificate changes follow Varnish’s load, commit, and reload workflow; backend TLS is independent of the public certificate. |
| Both terminate on separate hops | NGINX and/or Varnish, according to listener layout | Encrypted between components when configured | Provides hop-by-hop encryption but requires separate certificates, trust stores, names, and health checks. |
Choose one clear owner for each listener. Two services cannot bind the same address and port, and placing an HTTPS directive in a server block that is not on the active path will not secure traffic.
Varnish as an HTTPS client to its backend
Varnish can use HTTPS when it connects to a backend. In VCL, adding .ssl = 1; to the backend definition enables TLS from Varnish to that backend:
backend app_backend {
.host = "10.0.0.20";
.port = "443";
.ssl = 1;
}The backend certificate, trust behavior, and hostname expectations still need to match the way Varnish connects. This private upstream certificate is not the same asset as the public edge certificate served to browsers.
Varnish certificate reloads require a commit
Varnish’s TLS configuration has a staged change process. Load the new TLS material, commit the change, and then reload. The Varnish CLI documentation notes that a reload error rolls changes back and that a reload cannot proceed while TLS changes remain uncommitted. If a certificate reload fails, verify the certificate and key contents, inspect the CLI error, and confirm the new configuration was committed before trying again. The rollback behavior can preserve the previous working configuration, but it does not make an invalid new certificate usable.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Safe reload and live verification
- Run
sudo nginx -tand require a successful result. - Reload NGINX gracefully through the service manager, for example
sudo systemctl reload nginx, rather than restarting blindly. A graceful reload lets existing connections finish while workers adopt the validated configuration. - Check that the expected process is listening on the intended address and port with your operating system’s socket tool.
- Make a client request to the public hostname. Verify the certificate served, HTTP status, redirect behavior, and response headers that identify the intended proxy path.
- If Varnish is a separate hop, test both directions: the client-to-edge connection and the Varnish-to-backend connection. A successful browser handshake does not prove that the cache can reach an HTTPS origin.
- Keep the previous certificate and known-good configuration available until the new listener and upstream checks pass.
Fast diagnosis by error message
| Error text | Most likely meaning | First corrective action |
|---|---|---|
no "ssl_certificate" is defined |
An HTTPS listener lacks a certificate in the effective server block. | Use nginx -T, locate every listen 443 ssl;, and add or correct the certificate directives in the active block. |
cannot load certificate |
Bad path, unreadable file, invalid PEM, or certificate/key mismatch. | Check the path, permissions, PEM boundaries, chain order, and key pairing. |
BIO_new_file() failed |
NGINX cannot open a referenced file. | Inspect parent-directory traversal, symlinks, confinement policy, and ownership. |
PEM_read_bio_X509_AUX() failed |
Certificate contents or PEM formatting are invalid. | Replace the damaged or incorrectly formatted certificate with an intact PEM file. |
upstream SSL handshake failed |
Protocol, SNI, trust-chain, port, or client-certificate mismatch. | Test the backend directly and align scheme, name, protocol, CA, and mutual-TLS settings. |
configuration file ... test failed |
Final status line, not the underlying diagnosis. | Scroll upward and fix the earliest specific error. |
Preventing the next certificate outage
- Use stable certificate symlinks and verify their targets after every renewal.
- Keep private keys outside web roots and apply the narrowest workable permissions.
- Test the complete include tree with
nginx -Tduring deployment validation, not only the file being edited. - Automate
nginx -tas a gate before reloads; a failed test must stop the rollout. - Document which component terminates public TLS and which certificates belong to private upstream hops.
- Monitor certificate expiration and exercise the Varnish load/commit/reload procedure before an emergency change.
- Record the expected backend protocol, SNI name, trust CA, and whether client authentication is required.
The Bottom Line
Fix the first concrete error in the nginx -t output, validate the expanded configuration with nginx -T when includes are involved, and keep public and upstream TLS settings separate. After a successful test, reload NGINX gracefully; for Varnish, load and commit TLS changes before reloading so a bad certificate can be rejected without discarding the last working configuration.
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.
