Fix Niagara 4 Certificate and SSL Errors

Common Niagara 4 Certificate Error Messages

Technicians encounter these certificate errors in Workbench, the web UI, or platform daemon logs. Knowing the exact error message narrows the diagnosis:

• javax.net.ssl.SSLHandshakeException: sun.security.validator.ValidatorException: PKIX path building failed — The most common error. Workbench cannot verify the station's SSL certificate because it's self-signed, expired, or issued for a different hostname/IP.
• java.security.cert.CertificateExpiredException: NotAfter — The certificate's validity period has passed. Niagara's default self-signed certificates are typically valid for 1–3 years depending on the version.
• Certificate does not match the hostname — The station's IP address or DNS name changed after the certificate was generated. The SAN (Subject Alternative Name) field no longer matches the connection target.
• Platform daemon failed to start: SSL context initialization error — The platform daemon cannot load its keystore file. This typically happens after a version upgrade corrupts or changes the keystore format.
• Unable to connect to station: Connection refused (certificate) — Workbench rejects the connection because the station's certificate is untrusted. Older Niagara 4.x versions allowed bypassing this; 4.7+ enforces stricter validation by default.
• foxs: TLS handshake failed — The Fox protocol's secure variant (foxs) cannot complete the TLS handshake. Often paired with an expired or mismatched certificate on port 4911.

Cause 1: Expired Certificates

Niagara stations generate self-signed SSL certificates during initial commissioning. These certificates have a fixed validity period—typically 365 days on Niagara 4.4 and earlier, and up to 3 years on 4.7+. When the certificate expires, Workbench connections over foxs (port 4911) and HTTPS web UI connections (port 443 or custom) begin failing with CertificateExpiredException errors.

The station itself continues running. Points update, schedules fire, and BACnet communication remains unaffected because those protocols do not depend on the station's SSL certificate. But you lose the ability to connect via Workbench or the web dashboard until the certificate is renewed.

How to Diagnose

1. Open Workbench and attempt to connect to the station. If you see a certificate warning dialog, click View Certificate to check the expiration date in the Valid To field.
2. Alternatively, open a browser and navigate to https://<station-ip>:443. Click the padlock icon and inspect the certificate details. An expired certificate shows a Not After date in the past.
3. On the station's file system, check the keystore directly:

   # Check certificate expiration from the station's command line
   cd /opt/niagara/niagara-4.x.x.x/security
   keytool -list -v -keystore server.keystore -storepass <password>
   
   # Look for the "Valid from" and "until" dates in the output
   # Example output:
   # Valid from: Mon Jan 15 10:30:00 EST 2024 until: Tue Jan 14 10:30:00 EST 2025

How to Fix

Regenerate the station's certificate from Workbench (if you can still connect with a warning bypass) or from the station's local console:

# Option 1: From Workbench (if connection is possible with warning bypass)
# Navigate to: Platform > Certificate Management
# Click "Generate New Certificate"
# Set validity period (recommend 3 years / 1095 days)
# Restart the station after generation

# Option 2: From the station's local shell
# Stop the station first
/opt/niagara/niagara-4.x.x.x/bin/niagarad stop

# Use the Niagara security tool to regenerate
/opt/niagara/niagara-4.x.x.x/bin/niagarad security -certgen

# Restart the station
/opt/niagara/niagara-4.x.x.x/bin/niagarad start

On a JACE controller, the paths differ slightly. The Niagara installation lives under /niagara rather than /opt/niagara, and the keystore is typically at /niagara/security/server.keystore.

Cause 2: IP Address Change

When a Niagara station's certificate is generated, the station's current IP address and hostname are embedded in the certificate's Subject Alternative Name (SAN) field. If the station's IP changes—due to a DHCP reassignment, network reconfiguration, or physical relocation—the SAN no longer matches the IP that Workbench uses to connect. The result is a hostname mismatch error even though the certificate itself has not expired.

This is one of the most common certificate issues in the field. A technician changes the station's IP in the platform configuration, reboots, and then cannot reconnect via Workbench because the old IP is baked into the certificate.

How to Fix

1. If you can still connect using the old IP (before it's decommissioned), regenerate the certificate from Workbench first, then change the IP.
2. If the IP has already changed and Workbench refuses to connect, use the station's local console or SSH access:

   # SSH into the station or use a local console/keyboard
   # Navigate to the Niagara installation directory
   
   # On a supervisor (Linux/Windows):
   cd /opt/niagara/niagara-4.x.x.x
   
   # Regenerate the certificate with the new IP in the SAN
   bin/niagarad security -certgen
   
   # The tool will detect the current network interfaces and
   # include the new IP address in the SAN field automatically
   
   # Restart the station
   bin/niagarad restart

3. After regeneration, you may need to accept the new certificate in Workbench. Open the connection, review the certificate details to confirm the new IP appears in the SAN, and click Trust This Certificate.

To prevent this issue on stations with dynamic addressing, assign a static IP before commissioning. If you must use DHCP, configure a DHCP reservation so the address stays consistent.

Cause 3: Version Upgrade Issues

Major version upgrades—particularly from Niagara 4.4 to 4.7, or from 4.7 to 4.10+—can break certificate trust chains in several ways:

• Keystore format changes. Niagara 4.7 moved from JKS (Java KeyStore) to PKCS12 format. Stations upgraded from 4.4 may retain the old JKS keystore, which the new platform daemon cannot read.
• Stricter TLS enforcement. Niagara 4.7+ disabled TLS 1.0 and 1.1 by default. If the existing certificate was generated with parameters only valid for older TLS versions, the handshake fails.
• Trusted certificate store reset. The upgrade process may clear the client-side trusted certificate store in Workbench, requiring you to re-trust previously accepted station certificates.
• Java runtime changes. Niagara bundles its own JRE. Version upgrades often ship a newer JRE with different default security providers, which may reject certificates generated under the old JRE.

How to Fix After an Upgrade

# Step 1: Check if the keystore format is the issue
# Navigate to the security directory
cd /opt/niagara/niagara-4.x.x.x/security

# Check the keystore type
keytool -list -keystore server.keystore
# If it prompts for a keystore type or throws an error about
# "Invalid keystore format", the keystore needs migration

# Step 2: Migrate JKS to PKCS12 (if applicable)
keytool -importkeystore \
  -srckeystore server.keystore \
  -srcstoretype JKS \
  -destkeystore server.p12 \
  -deststoretype PKCS12 \
  -srcstorepass <password> \
  -deststorepass <password>

# Step 3: Back up the old keystore and replace
cp server.keystore server.keystore.bak
mv server.p12 server.keystore

# Step 4: Or simply regenerate (simplest approach)
# This creates a fresh certificate in the correct format
/opt/niagara/niagara-4.x.x.x/bin/niagarad security -certgen

# Step 5: Restart the station
/opt/niagara/niagara-4.x.x.x/bin/niagarad restart

If you are upgrading multiple stations, regenerating certificates is almost always faster than migrating keystores. Plan certificate regeneration as a standard step in your upgrade checklist.

Platform Daemon Certificate Errors

The platform daemon (niagarad) manages station lifecycle, remote connections, and software provisioning. It maintains its own certificate and keystore, separate from the station's certificate. When the platform daemon's certificate fails, the station cannot start, and you see errors like Platform daemon failed to start in the system logs.

Symptoms

• The station does not appear in Workbench at all—not even with a certificate warning. The daemon process is not running.
• System logs (syslog on Linux, Event Viewer on Windows) show Java SSL exceptions during daemon startup.
• The niagarad process starts briefly and then exits within seconds.

Platform Daemon Fix

# Check platform daemon logs for the specific error
# Linux:
cat /opt/niagara/niagara-4.x.x.x/var/log/niagarad.log | tail -50

# Windows:
type "C:\Niagara\niagara-4.x.x.x\var\log\niagarad.log"

# Common fix: regenerate the platform daemon's certificate
# Stop any running instance first
/opt/niagara/niagara-4.x.x.x/bin/niagarad stop

# Delete the corrupted platform keystore
# Back it up first
cp /opt/niagara/niagara-4.x.x.x/security/platform.keystore \
   /opt/niagara/niagara-4.x.x.x/security/platform.keystore.bak

rm /opt/niagara/niagara-4.x.x.x/security/platform.keystore

# Restart the daemon - it will generate a new keystore on startup
/opt/niagara/niagara-4.x.x.x/bin/niagarad start

# Verify the daemon is running
/opt/niagara/niagara-4.x.x.x/bin/niagarad status

On JACE controllers, the platform daemon keystore is at /niagara/security/platform.keystore. The same delete-and-regenerate approach works. If the JACE has no local console access, you may need to remove the SD card, delete the keystore file from a laptop, and reinsert the card.

After regenerating the platform daemon certificate, any Workbench instance that previously trusted the old daemon certificate will need to re-accept the new one on first connection.

Regenerating Niagara Certificates: Step-by-Step

This section consolidates the complete certificate regeneration procedure with all relevant file paths for both supervisors and JACE controllers.

Supervisor (Linux)

# 1. Stop the station
/opt/niagara/niagara-4.x.x.x/bin/niagarad stop

# 2. Back up existing keystores
cd /opt/niagara/niagara-4.x.x.x/security
cp server.keystore server.keystore.bak.$(date +%Y%m%d)
cp platform.keystore platform.keystore.bak.$(date +%Y%m%d)

# 3. Regenerate station certificate
/opt/niagara/niagara-4.x.x.x/bin/niagarad security -certgen

# 4. Verify the new certificate
keytool -list -v -keystore server.keystore -storepass <password> | grep -A2 "Valid from"

# 5. Start the station
/opt/niagara/niagara-4.x.x.x/bin/niagarad start

# 6. Confirm station is running
/opt/niagara/niagara-4.x.x.x/bin/niagarad status

Supervisor (Windows)

REM 1. Stop the Niagara service
net stop NiagaraDaemon

REM 2. Back up existing keystores
cd C:\Niagara\niagara-4.x.x.x\security
copy server.keystore server.keystore.bak
copy platform.keystore platform.keystore.bak

REM 3. Regenerate station certificate
C:\Niagara\niagara-4.x.x.x\bin\niagarad.exe security -certgen

REM 4. Start the Niagara service
net start NiagaraDaemon

JACE 8000

# 1. SSH into the JACE (default port 22)
ssh admin@<jace-ip>

# 2. Stop the station
/niagara/bin/niagarad stop

# 3. Back up existing keystores
cd /niagara/security
cp server.keystore server.keystore.bak
cp platform.keystore platform.keystore.bak

# 4. Regenerate certificate
/niagara/bin/niagarad security -certgen

# 5. Start the station
/niagara/bin/niagarad start

# Alternative: If SSH is unavailable, use the JACE's local
# web-based Platform Administration page at:
# https://<jace-ip>:3011/admin
# Navigate to Certificate Management to regenerate

Workbench Client-Side Trust Store

After regenerating certificates on the station, Workbench may still refuse to connect because it remembers the old certificate. Clear the client-side trust store:

# Workbench trust store location:
# Windows: C:\Users\<username>\Niagara4\security\truststore.jks
# Linux:   ~/niagara/security/truststore.jks
# macOS:   ~/niagara/security/truststore.jks

# Option 1: Delete the trust store (Workbench will re-prompt for all stations)
rm ~/niagara/security/truststore.jks

# Option 2: Remove a specific certificate from the trust store
keytool -delete -alias <station-alias> -keystore ~/niagara/security/truststore.jks

Common Niagara Certificate Mistakes

• Ignoring certificate warnings and clicking "Trust Always." While this bypasses the error temporarily, it masks real problems like expired certificates or man-in-the-middle attacks. Regenerate the certificate properly instead of trusting a broken one. In Niagara 4.7+, Tridium restricted the ability to bypass certificate warnings for good reason.
• Changing the station IP without regenerating the certificate. The certificate's SAN field must match the IP or hostname used for the connection. Change the IP and regenerate the certificate in the same maintenance window. Do the cert regeneration after the IP change, not before, so the new IP is captured in the SAN.
• Copying keystores between stations. Each Niagara station must have a unique certificate. Copying server.keystore from one station to another causes both stations to present the same certificate with the wrong IP/hostname in the SAN. It also creates a security vulnerability since both stations share the same private key.
• Forgetting the platform daemon has a separate certificate. The station certificate and the platform daemon certificate are independent. Regenerating one does not fix the other. If both are expired or corrupted, you need to address both keystores: server.keystore (station) and platform.keystore (daemon).
• Not backing up keystores before making changes. Always copy the existing keystore files before deleting or regenerating. If the regeneration fails or produces unexpected results, you can restore the backup and try a different approach. A broken keystore with no backup means a complete reconfiguration of certificate trust across all connected Workbench clients.

Platform and Version Compatibility

Certificate handling varies across Niagara versions and hardware platforms. The following table summarizes key differences:

Hardware platform differences:

Sources and Attribution

The technical guidance in this entry is informed by the following sources:

• OneSight Help Center — OneSight by Lynxspring. Documentation on Niagara platform administration, including certificate management and platform daemon troubleshooting for JACE and supervisor platforms.
• Niagara Certificate Error Discussions — HVAC-Talk Forum. Field technician discussions covering certificate expiration, IP change scenarios, and Workbench trust store issues across multiple Niagara 4 versions.
• Tridium Niagara 4 Hardening Guide — Tridium, Inc. Official security guidance covering TLS configuration, keystore management, certificate generation procedures, and platform daemon security settings for Niagara 4.x installations.
• Tridium Niagara 4 Platform Guide — Tridium, Inc. Platform administration reference including niagarad command-line options, security directory structure, and certificate lifecycle management.
• Oracle keytool Documentation — Oracle. Reference for the Java keytool utility used to manage Niagara keystores, including certificate inspection, keystore format migration, and trust store operations.