How to Fix SSL Certificate Errors in Wowza Streaming Engine

SSL certificate issues in Wowza Streaming Engine can break WebRTC playback, block HTTPS access, and trigger browser trust warnings. This guide explains how to diagnose and fix the most common SSL errors, including WebSocket connection failures, keystore issues, TLS mismatches, and certificate chain problems.

The Main Causes of SSL Certificate Issues in Wowza Streaming Engine

Most SSL issues in Wowza Streaming Engine come from one of four root causes:

1. A missing or misconfigured JKS keystore
2. A port that is not bound to HTTPS
3. A certificate chain that is incomplete or self-signed without browser trust
4. A TLS protocol or cipher mismatch between the client and the server.

Diagnose the issue by tracing the error messages or symptoms, and finding the likely underlying cause of that issue, in this quick reference table:

What Are Common SSL Issues in Wowza Streaming Engine?

Secure Sockets Layer (SSL) is often a factor behind three of the most disruptive failures in a Wowza Streaming Engine deployment:

1. Wowza Streaming Engine Manager goes dark over HTTPS
2. The player page shows a “Not Secure” warning, blocking adoption
3. WebRTC delivery breaks with the “WebSocket Connection Failed” error in the browser console

The root cause behind these issues is often the SSL configuration not matching what the browser, the WebSocket client, or the JVM expects.

How SSL Works in Wowza Streaming Engine

Wowza Streaming Engine relies on the JVM’s standard SSL stack. The certificate lives inside a Java KeyStore (JKS) file, and Wowza references that file in VHost.xml under the <HostPort> configuration block for the secure port. The same VHost.xml entry defines which port listens for HTTPS traffic, which <SSLConfig> properties to apply, and which cipher suites and protocols the JVM should negotiate.

Three ports matter for SSL troubleshooting:

1. Port 443 (or another configured secure host port) carries HTTPS traffic, HLS over HTTPS, and the WebSocket Secure (WSS) connection used by WebRTC.
2. Port 8090 is the usual HTTPS port for Wowza Streaming Engine Manager. SSL settings are managed in the tomcat.properties file. Port 8088 is usually used for HTTP, but not HTTPS.
3. Port 8087 is the REST API port. HTTPS access here requires its own SSL binding.

WebRTC publishing and playback in Wowza Streaming Engine require WSS, not WS. The browser refuses to upgrade an insecure WebSocket connection from a page already running over HTTPS, and modern browsers refuse to establish WebRTC at all without a valid TLS handshake. That dependency makes SSL the gating factor for every WebRTC deployment. Understanding SSL/TLS is crucial to ensuring there are no unforeseen issues.

How to Fix Common SSL Certificate Errors in Wowza Streaming Engine

Why does the browser show “Not Secure” or ERR_CERT_AUTHORITY_INVALID?

A self-signed certificate or an incomplete certificate chain causes the error. Browsers trust certificates that chain up to a root certificate authority in their trust store. A self-signed cert has no such chain. A CA-issued cert with a missing intermediate certificate breaks the chain even though the leaf is valid.

To fix it:

1. Run keytool -list -v -keystore [path-to-jks] and confirm the keystore contains the full chain, not just the leaf certificate.
2. If intermediates are missing, import them with keytool -import -trustcacerts -alias intermediate -file intermediate.crt -keystore [path-to-jks].
3. Restart Wowza Streaming Engine and re-test in an incognito browser window to bypass cached TLS state.

For production deployments, a CA-issued or Wowza StreamLock certificate avoids the trust problem entirely.

How do I fix “Could not load keystore” in the Wowza logs?

This error appears in wowzastreamingengine_access.log when the JVM cannot open the JKS file referenced in VHost.xml. Three checks resolve almost every instance:

1. Check The Path
   Confirm the KeyStorePath value in VHost.xml points to the actual file location. Relative paths resolve against the Wowza install directory, not the user’s working directory.
2. Check The Password
   Compare the KeyStorePassword in VHost.xml against the password set when creating the JKS file. A trailing space or a pasted control character will fail silently.
3. Check The Format
   Wowza Streaming Engine defaults to JKS format. If the file was exported as PKCS12 (.p12 or .pfx), either convert it with keytool -importkeystore or set the KeyStoreType property to PKCS12 in VHost.xml.

How do I create a self-signed SSL certificate for Wowza Streaming Engine?

Generate a self-signed certificate with Java’s keytool utility:

keytool -genkeypair -alias wowza -keyalg RSA -keysize 2048 \
  -validity 365 -keystore [name].jks -storepass [password]

The Wowza doc on creating a self-signed SSL certificate covers the full keytool syntax and Wowza-specific options. A self-signed cert works fine for local development and isolated lab testing. However, every team member’s browser and OS must import the cert into the local trust store, or the Manager and any WebRTC page will throw certificate warnings. Also, WebRTC clients on mobile devices will reject the cert outright, breaking publishing and playback from phones and tablets. For any shared or external-facing environment, request a certificate from a CA or use Wowza StreamLock.

How do I install a CA-issued or StreamLock certificate?

Request an SSL certificate from a certificate authority to install a CA-issued or StreamLock certificate. To install a CA-issued certificate:

1. Generate a Certificate Signing Request (CSR)
2. Submit the CSR to the CA, and receive the signed certificate in return
3. Import the signed certificate and any intermediate certificates back into the same JKS file used to generate the CSR, and ensure the key is in a keystore
4. Update VHost.xml with the keystore path, password, and the secure port.
5. Restart Wowza Streaming Engine and verify the chain with an SSL checker.

To install a StreamLock certificate:

1. Request the jks from the Wowza StreamLock portal
2. Update VHost.xml with the keystore path, password, and the secure port.
3. Restart Wowza Streaming Engine and verify the chain with an SSL checker.

Fix WebRTC WebSocket Connection Failed in Wowza Streaming Engine

WebRTC in Wowza Streaming Engine requires a secure WebSocket (WSS) connection. The “WebSocket Connection Failed” error in the browser console almost always means the browser cannot establish a trusted TLS connection to the Wowza WebSocket port. The fix is to bind a valid SSL certificate to the WebSocket port in VHost.xml, confirm the certificate is trusted by the client browser, and verify the WebSocket port is reachable through any intervening firewall or load balancer.

Run the following checks in order. Most teams find their issue within the first three.

Quick Diagnostic Checklist for WebRTC WebSocket Failures

1. VHost.xml has an <SSLConfig> block on the WebSocket port.
2. The certificate is trusted by the client browser, or a CA-issued cert is in place.
3. The player page uses wss://, not ws://.
4. curl -vk https://[host]:[port]/ completes the TLS handshake.
5. The WebRTC application is enabled in Wowza Streaming Engine Manager.
6. DevTools WS tab shows a 101 Switching Protocols response.

1) Confirm the WebSocket port has an SSL binding in VHost.xml

Open VHost.xml and locate the <HostPort> entry for port 443 (or the configured secure WebSocket port). The block must include an <SSLConfig> section with KeyStorePath, KeyStorePassword, and KeyStoreType set. Without this, Wowza Streaming Engine listens on the port as plain TCP, and every WSS handshake fails.

2) Verify the certificate is trusted by the browser

A self-signed certificate breaks WebRTC even when the WebSocket port has the right binding. Chrome and Firefox both block the WSS handshake silently when the certificate is not trusted, with no visible warning beyond the failed WebSocket entry in DevTools. Add the cert to the OS or browser trust store, or switch to a CA-issued certificate for any environment beyond local development.

3) Check for mixed-content blocking

A page served over HTTPS that points to a ws:// endpoint instead of wss:// triggers mixed-content blocking in every modern browser. Open the WebRTC example page or the custom player and confirm the WebSocket URL begins with wss:// and matches the secure host port in VHost.xml.

4) Verify the WebSocket port reaches Wowza

Before blaming WebRTC, run curl -vk https://[host]:[port]/ from a client machine. A successful TLS handshake plus a 404 or other HTTP response confirms the port is open and SSL is negotiating. A connection refused or TLS handshake failure means a firewall is blocking the port, the SSL config has a fault, or the service has stopped.

In Chrome DevTools, the Network tab with the WS filter shows the WebSocket handshake attempt and the exact failure code. A 101 Switching Protocols response means the upgrade succeeded. Anything else points to a TLS or routing issue ahead of Wowza.

5) Confirm the WebRTC application is enabled

The WebRTC application in Wowza Streaming Engine Manager must be enabled, and the SDP exchange endpoint must be reachable on the same secure host. Set up WebRTC streaming with Wowza Streaming Engine and make sure to follow the application-level configuration steps.

How to Improve SSL/TLS Performance in Wowza Streaming Engine

Java 9 introduced significant performance improvements in the JVM’s SSL stack, including better support for elliptic-curve cryptography and faster handshake negotiation. Wowza Streaming Engine installs Java 21 by default, but instances running on older versions often show high CPU during the SSL handshake phase, especially under concurrent WebRTC load. Improve SSL performance with Java 9 using specific JVM flags and property settings. Three steps unlock most of the available performance:

1. Confirm the active Java version
   Run java -version against the Wowza-bundled JVM. The recommended baseline for production SSL workloads is Java 11 or later, with Java 17 LTS preferred for new deployments.
2. Prefer ECDHE cipher suites
   Elliptic-curve key exchange runs faster than RSA and pairs well with modern certificates. Configure cipher suite ordering in Tune.xml.
3. Tune the SSL session cache
   For high-concurrency WebRTC and HLS-over-HTTPS workloads, a larger session cache reduces full handshake overhead on returning clients.

SSL/TLS Security Best Practices for Wowza Streaming Engine

A working SSL config and a hardened SSL config are not the same. Operational maturity requires four practices.

1. Disable legacy TLS versions
   TLS 1.0 and 1.1 carry known weaknesses and break in modern browsers. Set the minimum protocol to TLS 1.2 with TLS 1.3 enabled where the JVM supports it.
2. Tune cipher suite ordering for 2026
   Prefer ECDHE-RSA-AES128-GCM-SHA256 and ECDHE-RSA-AES256-GCM-SHA384, with AES-128 ahead of AES-256 for performance. Remove CBC-mode and RC4 suites entirely.
3. Monitor certificate expiration
   The most common SSL outage happens the day a certificate expires. Add expiration monitoring to the same alerting system that watches stream health, and rotate certificates at least 30 days before expiration.
4. Log and alert on handshake failures
   A spike in SSL handshake errors in wowzastreamingengine_access.log signals expiring intermediates, broken client trust stores, or a misrouted port. Feed the log into the standard observability stack rather than waiting for users to report failures.

When to Escalate

If the diagnostic checklist does not resolve the issue, gather the following before contacting support:

• The relevant <HostPort> block from VHost.xml with the password redacted
• The output of keytool -list -v -keystore [path-to-jks]
• The relevant entries from wowzastreamingengine_access.log and wowzastreamingengine_error.log
• The browser DevTools Network WS tab output for WebRTC failures
• The exact Wowza Streaming Engine version and JVM version

For deeper diagnostic walkthroughs of non-SSL issues, see the companion post on Troubleshooting Common Streaming Configuration Issues in Wowza Streaming Engine. The Wowza Community page offers the fastest path to peer review on edge cases.

Keep Your Streams Secure

SSL configuration stays invisible when it works and becomes catastrophic when it breaks. By starting from the symptom, mapping it back to the underlying cause, and verifying each layer of the TLS stack in order, technical teams can resolve the vast majority of Wowza Streaming Engine SSL and WebRTC WebSocket issues in minutes rather than hours. To deploy a modern, flexible, and reliable media server, talk to a Wowza expert today.

Frequently Asked Questions

What is the most common SSL error in Wowza Streaming Engine?

The most common SSL error is “Could not load keystore,” caused by a wrong path, wrong password, or wrong format in VHost.xml. Verify the JKS file with keytool -list -keystore and confirm the password matches the value set in <SSLConfig>.

Why is my Wowza WebRTC stream not connecting?

WebRTC failures in Wowza Streaming Engine almost always trace back to an SSL or WebSocket issue. Confirm the WebSocket port has a valid SSL certificate bound in VHost.xml, the certificate is trusted by the browser, and the page hosting the player runs over HTTPS with a wss:// WebSocket URL.

Can I use a self-signed certificate with Wowza WebRTC?

A self-signed certificate works for local development, but it must be imported into the OS or browser trust store on every client machine. For staging or production, use a CA-issued certificate or a Wowza StreamLock certificate.

How do I check if my SSL certificate is correctly installed in Wowza?

Run keytool -list -v -keystore [path-to-jks] and confirm the certificate chain runs cleanly from the leaf to the root CA. Then open https://[host]:[port]/ in a browser and verify the connection shows as trusted with no warnings.

Does Wowza Streaming Engine support TLS 1.3?

Yes, when Wowza Streaming Engine runs on a Java 11 or later JVM. Configure cipher suite ordering in Tune.xml and set the minimum protocol version to TLS 1.2 or higher.

Why is my Wowza Streaming Engine Manager not reachable over HTTPS?

Wowza Streaming Engine Manager listens on port 8088 for HTTP. To enable HTTPS access, configure a secure host port in manager/conf/tomcat.properties with a valid SSL certificate, then restart the Wowza Streaming Engine service. Port 8090 is the port usually enabled for HTTPS. See Wowza’s Connect to Wowza Streaming Engine Manager over HTTPS doc for the full process.

How do I improve SSL handshake performance in Wowza?

Run Wowza Streaming Engine on Java 9 or later, prefer ECDHE-based cipher suites, and keep RSA keys at 2048 bits unless compliance requires 4096. For high-concurrency WebRTC workloads, also increase the SSL session cache size in Tune.xml.