Qntrl Bridge Online Help | Qntrl Bridge Troubleshooting FAQ

Bridge Troubleshooting FAQs

1. Prerequisites & System Requirements   

1.1 What are the prerequisites for installing and using Qntrl Bridge?   

Before installing Qntrl Bridge, ensure the following prerequisites are met:

  • Administrative (Windows) or sudo (Linux/macOS) privileges are required to install Bridge.

  • A non-administrator (Windows) or non-root (Linux/macOS) local user account must be available to run the Bridge service after installation.

  • The Bridge host has outbound internet access to Qntrl endpoints over HTTPS/WSS (Port 443).

  • The Bridge installation directory has read and write permissions for the Bridge service user.

Notes
Administrator or root privileges are needed only during installation. The Bridge service itself must run under a non-administrator or non-root user account for security reasons.

 

1.2 What are the hardware and software requirements for Qntrl Bridge?   

Qntrl Bridge includes the required runtime components and does not require separate installation of Java or PostgreSQL.
The installation package includes:
  • Java Runtime Environment (JRE)
  • PostgreSQL database
Depending on the operating system, standard utilities such as PowerShell, bash, or systemd may be required for installation and service management.
For supported hardware specifications, operating systems, and software dependencies, refer to Bridge Sytem Requirements.

1.3 Can Bridge be installed as the root or Administrator user?   

No. For security and compatibility reasons, install Bridge using a dedicated service account with the required privileges.
Running Bridge as the root or Administrator user is not recommended, as it can lead to permission conflicts and PostgreSQL-related issues.

 

1.4 What network access is required before installing Bridge?   

The Bridge host must have outbound access to the following Qntrl endpoints:

Target

Port

Protocol

core.qntrl.com

443

HTTPS / WSS

bridgews.qntrl.com

443

HTTPS / WSS

Ensure outbound HTTPS traffic over Port 443 is not intercepted in a way that blocks or modifies WebSocket (WSS) connections.

The Qntrl endpoints may vary based on your data center — refer to the Allowed IP Addresses help page for the endpoints specific to your region.

2. Installation Issues   

2.1 Why does Bridge installation fail?   

Follow these steps to identify and resolve the installation issue.

  1. Check the Bridge logs: Navigate to <Bridge-path>/logs/ and check the available log files:
    1. If logs.txt exists, review it for installation or startup errors.
    2. If logs.txt is not available, check wrapper.log.gz for diagnostic information.
  2. Verify Bridge registration: 
    1. Sign in to your Qntrl organization and navigate to Settings (⚙) >> Bridge >> Bridge
    2. If the Bridge is not listed, it was unable to register with Qntrl. Proceed to the next step.
  3. Verify the installation environment: Ensure the following requirements are met:
    1. Port Availability: Verify that ports 8500 and 8501 are not being used by another process.
    2. Outbound Connectivity: Ensure outbound HTTPS/WSS (Port 443) access is allowed to:
      1. core.qntrl.com
      2. bridgews.qntrl.com
    3. Proxy Configuration: If your environment uses an outbound proxy, verify that the proxy is configured correctly. Refer to Proxy Configuration.

 

2.2 Why does Bridge fail to start when installed in a non-default folder on Linux or macOS?   

The Bridge installation directory must be accessible to the Bridge service user.
  • On macOS, avoid installing Bridge in protected folders such as:
    • Desktop
    • Documents
    • Downloads
  1. On Linux, ensure the Bridge service user has read and write access to the installation directory.
 

2.3 Why is the Bridge not listed in Qntrl after installation?   

This usually means Bridge could not register with Qntrl.

  1. Go to Settings >> Bridge >> Bridge and check whether the Bridge entry is available.

  2. If it is not listed, verify outbound connectivity to:

    1. core.qntrl.com

    2. bridgews.qntrl.com

  3. Ensure HTTPS/WSS traffic over port 443 is allowed.

  4. Check whether a firewall, proxy, or security appliance is blocking WebSocket traffic.

  5. Review logs.txt or wrapper.log.gz for registration or WebSocket errors.


3. Bridge Startup Issues   

3.1 How do I start or stop the Bridge?   

Use the following commands to start or stop the Bridge service.

Linux / macOS:

sh <Bridge-path>/bin/bridge.sh start   # Start
sh <Bridge-path>/bin/bridge.sh stop    # Stop

Windows:

<Bridge-path>\bin\bridge.bat start     :: Start
<Bridge-path>\bin\bridge.bat stop      :: Stop

3.2 How do I restart the Bridge?   

Linux / macOS:

sh <Bridge-path>/bin/bridge.sh restart

Windows (command line):

<Bridge-path>\bin\bridge.bat restart

Windows (using the Bridge UI): 

Go to Settings (⚙) >> Bridge >> Bridge, click the Actions menu next to the required Bridge, and select Restart.

 

3.3 What should I do if Bridge fails to start?   

Follow these steps to identify and resolve the issue.

Step 1: Check the Bridge logs

  • Navigate to <Bridge-path>/logs/

  • Review the following log files:

    • logs.txt – Check for Bridge startup or runtime errors.

    • wrapper.log.gz – Review this file if logs.txt is unavailable.

If you need to share the logs with Qntrl Support, use the following commands:

  • Linux / macOS: <Bridge-path>/bin/bridge.sh send_logs

  • Windows: <Bridge-path>\bin\bridge.bat send_logs

 

Step 2: Verify port availability  

Ensure the following ports are not being used by another application:

Port

Purpose

8500

Bridge Web UI

8501

Bundled PostgreSQL

 

Step 3: Verify directory permissions  

Ensure the Bridge service user has read and write access to the Bridge installation directory. Insufficient permissions can prevent Bridge from creating log files and starting successfully.


Step 4: Verify outbound connectivity  

Ensure outbound HTTPS/WSS (Port 443) access is allowed to the following Qntrl endpoints:
  • core.qntrl.com
  • bridgews.qntrl.com
Also ensure that WebSocket (WSS) traffic is not blocked or intercepted by a firewall, proxy, or network security appliance.

Step 5: Verify proxy configuration  

If your environment uses an outbound proxy, ensure that it is configured correctly. Refer to Proxy Configuration.

After updating the proxy configuration, restart the Bridge and verify that it starts successfully.

 

3.4 What should I do if Bridge does not start after a system reboot on Windows?   

Resolution

  1. Open Windows Services.
  2. Check whether Qntrl Bridge is listed and running.
  3. If it is not running, start it manually using the command: <Bridge-path>\bin\bridge.bat start
  4. Set the Qntrl Bridge service startup type to Automatic.
  5. If the service fails to start, review the Bridge logs.

4. Bridge Inactive or Not Visible   

4.1 The Bridge is inactive. What should I check?   

If the Bridge is inactive, perform the following checks.

  • Check whether the Bridge service is running.

    • Linux / macOS: sh <Bridge-path>/bin/bridge.sh status

    • Windows: <Bridge-path>\bin\bridge.bat status

  • If the Bridge is not running, start it.

    • Linux / macOS: sh <Bridge-path>/bin/bridge.sh start

    • Windows: <Bridge-path>\bin\bridge.bat start

  • Ensure that the Bridge is listening on the default port 8500.

    • Linux / macOS: ss -tlnp | grep 8500

    • Windows: netstat -ano | findstr 8500

  • If the Bridge is running and the port is listening but it is still inactive in Qntrl, check logs.txt and wrapper.log.gz in <Bridge-path>/logs/ for errors.

  • Ensure the Bridge host has outbound HTTPS/WSS (Port 443) access to the required Qntrl endpoints. For more information, refer to Connectivity & Network Issues.


4.2 Why is Bridge installed and started but not visible in Qntrl?   

  • Confirm the Bridge host can reach:

    • core.qntrl.com

    • bridgews.qntrl.com

  • Verify proxy settings if your environment uses a proxy. Refer to Proxy Configuration.

  • Check Bridge logs for WebSocket connection or registration errors.

  • Ensure no firewall or security appliance is blocking WSS traffic over port 443.

 

5. Connectivity and Network Issues   

5.1 What Qntrl endpoints must be reachable from the Bridge host?   

Domain

Port

Protocol

core.qntrl.com

443

HTTPS / WSS

bridgews.qntrl.com

443

HTTPS / WSS

For region-specific domains and IP ranges, refer to Allowed IP Addresses. 

 

5.2 Does Bridge support fully offline or air-gapped environments?   

No. Bridge requires outbound HTTPS/WebSocket connectivity to Qntrl over port 443.

If direct internet access is restricted, configure an outbound proxy to reach the required Qntrl endpoints.

 

A minimum of 100 Mbps LAN bandwidth is recommended. Lower bandwidth may reduce throughput for high task volumes.


5.4 Does Bridge require time synchronization?   

Yes. Accurate time synchronization is required on the Bridge host, and on any AD/LDAP servers, databases, or remote systems that Bridge integrates with.

  • Use NTP or an equivalent time synchronization service.

  • Keep clock skew within ±5 minutes maximum (stricter limits may apply for Kerberos or certificate-based authentication).


6. Proxy Configuration   

6.1 How do I configure Bridge to use an outbound proxy?   

If your environment requires outbound traffic to pass through a corporate proxy:

  1. Run the following command and follow the prompts:

    • Linux / macOS: <Bridge-path>/bin/bridge.sh configure_proxy

    • Windows: <Bridge-path>\bin\bridge.bat configure_proxy

  2. Restart the Bridge service after completing the configuration. Supported proxy ports: 8080, 3128, 443.


6.2 Why does Bridge fail to connect even though the proxy is configured?   

This may happen if the proxy blocks or modifies WebSocket traffic.

  • Confirm the proxy allows WebSocket traffic over port 443.

  • Verify proxy credentials if authentication is required.

  • Check whether SSL inspection is breaking the TLS connection.

  • If required, exclude Qntrl endpoints from SSL inspection or upload the proxy CA certificate to the Bridge Truststore. Refer to Certificate Issues.


7. Certificate Issues   

7.1 Why do certificate errors occur when Bridge calls internal domains or IPs?   

This can occur when the target internal service uses a self-signed or privately issued certificate that is not trusted by the Bridge host.

Resolution:

  1. Extract the certificate:
    1. openssl s_client -connect <domain:port> -showcerts
    2. Copy only the certificate block (the -----BEGIN CERTIFICATE----- ... -----END CERTIFICATE----- section) and save it as a .pem file. Alternatively, export the certificate via your browser.
  2. Upload the certificate to Bridge:

    1. Open the Bridge Agent Web UI at http://<bridge-host>:8500.

    2. Navigate to /account/ssl.

    3. Under the Truststore section, upload the exported .pem certificate.

The uploaded certificate is added to the Bridge Truststore and will be used to establish secure connections with the target service.


7.2 How do I enable HTTPS for the Bridge Web UI?   

Open the Bridge Web UI at http://<bridge-host>:8500/account/ssl and provide the certificate details.

The fields available are:

Field

Required

Root Certificate

Optional

Intermediate Certificate

Optional

Server Certificate

Required

Private Key

Required

Private Key Password

Required only if the key is password-protected

  • Self-signed certificate: Upload the Server Certificate and Private Key.

  • CA-signed certificate: Upload the Server Certificate, Private Key, and the appropriate Root and Intermediate Certificates in the certificate chain. 


8. Reinstalling and Uninstalling Bridge   

8.1 How do I reinstall Bridge?   

  • Linux / macOS

    • sudo sh <Bridge-path>/bin/bridge.sh uninstall

    • sudo sh <Bridge-path>/bin/bridge.sh installstart

  • Windows

    • <Bridge-path>\bin\bridge.bat uninstall

    • <Bridge-path>\bin\bridge.bat installstart

 

8.2 How do I fully uninstall Bridge?   

Follow these steps to completely remove the Bridge from your system.

Windows:  

  1. Remove the Bridge service: <Bridge-path>\bin\bridge.bat uninstall

  2. Delete the Bridge installation directory:

    • Command Prompt: rd /s /q <Bridge-path>

    • PowerShell: Remove-Item -Recurse -Force <Bridge-path>

Linux / macOS:  

  1. Remove the Bridge service: sh <Bridge-path>/bin/bridge.sh uninstall

  2. Delete the Bridge installation directory: rm -rf <Bridge-path>

NotesEnsure you have the required administrative or sudo privileges before running these commands.

9. Multiple Bridge Instances   

9.1 Can I install multiple Bridge instances in the same Qntrl organization?   

Yes. You can install and connect multiple Bridge instances to the same Qntrl organization.

Multiple Bridge instances are useful for:

  • Connecting to different network segments (for example, DMZ and internal LAN)

  • Separating production and non-production environments

  • Distributing different types of workloads across Bridge instances

  

9.2 How are tasks distributed across multiple Bridge instances?   

Qntrl distributes tasks across the available Bridge instances in a load-balancing cluster, helping balance the workload and improve overall availability. As additional Bridge instances are added to the cluster, tasks are automatically distributed across the available instances.

For more information about configuring load-balancing clusters, refer to Bridge Load Balancing Clustering.

 

9.3 What happens if one Bridge instance becomes unavailable?   

Tasks can be rerouted to other available Bridge instances configured within the same Qntrl organization.

For high availability configuration, refer to the Bridge Cluster.

10. Database (PostgreSQL)   

10.1 Can Bridge use an external PostgreSQL instance instead of the bundled database?   

Yes. Bridge supports using an external PostgreSQL instance.

You can configure it in either of the following ways:

  • During installation: Specify the external PostgreSQL instance when prompted.

  • After installation: Run the following command:

    • Linux / macOS: bin/bridge.sh configure_postgres

    • Alternatively, update the PostgreSQL configuration directly in: <Bridge-path>/conf/postgres.xml


10.2 What version of PostgreSQL is bundled with Bridge?   

Bridge includes PostgreSQL 16.4.

By default, the bundled database:

  • Listens only on localhost

  • Uses port 8501

  • Is not accessible externally


10.3 Which databases can Bridge connect to?   

Bridge supports connecting to the following databases on target systems.

Database

Supported Versions

MySQL

5.x, 8.x

PostgreSQL

14 and later

Oracle

19c, 21c

SQL Server

2019, 2022

Notes

If newer database versions require updated JDBC drivers, replace the existing drivers with compatible versions.


11. Logs and Diagnostics   

11.1 Where are the Bridge log files located?   

Log Type

Location

Rotation Policy

Bridge logs

<Bridge-path>/logs/logs.txt

Size-based; maximum 5 MB per file; the five most recent log files are retained.

Wrapper logs

<Bridge-path>/logs/wrapper.log

Same as above

Task logs

<Bridge-path>/logs/<SERVICE_DIR>/

Same as above


11.2 What should I look for in the Bridge logs?   

Review the log files for the following types of errors:

Error Type

Description

Connection errors

Network or firewall issues preventing communication with Qntrl endpoints.

Permission errors

The Bridge service user does not have sufficient access to the Bridge installation directory.

Port conflicts

Another application is using port 8500 or 8501.

Certificate errors

Bridge cannot validate the SSL/TLS certificate presented by an internal service.

WebSocket errors

The outbound WebSocket (WSS) connection to Qntrl is blocked or unexpectedly terminated.

 

11.3 How do I verify that Bridge is connected to Qntrl?   

You can verify the Bridge connection in either of the following ways:

  • Open the Bridge Web UI at http://<bridge-host>:8500 and check the Bridge connection status.

  • Review logs.txt for successful WebSocket connection and Bridge registration messages.


12. Security and Permissions   

12.1 What TLS version does Bridge use to connect to Qntrl?   

Bridge uses TLS 1.3 or later for all outbound HTTPS and WebSocket Secure (WSS) connections to Qntrl.


12.2 What service account should Bridge use?

For information about the recommended Bridge service account, refer to Prerequisites & System Requirements.

 

12.3 Are there any browser requirements for accessing the Bridge Web UI?   

The Bridge Web UI supports modern web browsers.

For the list of supported browsers, browser versions, and minimum screen resolution, refer to Bridge System Requirements.


13. Backup and Recovery   

13.1 What Bridge data should I back up?   

Back up the following Bridge data to support recovery after a system failure.

Data

Location

PostgreSQL data directory

<Bridge-path>/pgsql/data

Configuration files

<Bridge-path>/conf

The configuration directory includes Bridge settings, certificates, encryption keys, and connection information.

Use your organization's standard file-level or snapshot-based backup solution to back up these directories regularly.


13.2 How do I recover Bridge after a host failure?   

  1. Follow these steps to recover Bridge on a new host.

  2. Install or redeploy Qntrl Bridge on a compatible host.

  3. Restore the following directories from your backup:

    1. <Bridge-path>/pgsql/data

    2. <Bridge-path>/conf

  1. Start the Qntrl Bridge service.

  2. Confirm that:

    1. Bridge reconnects successfully to Qntrl.

    2. Tasks are processed successfully.

    3. Task history is available in both Qntrl and the Bridge Web UI.


Still Need Help?   

If the issue persists, submit a support ticket and include the Bridge logs for faster troubleshooting.

    • Related Articles

    • Install and Configure Bridge

      Bridge is a lightweight agent that enables secure communication between Qntrl and your on-premise systems. This article provides step-by-step instructions to install Bridge across supported platforms. Supported Platforms Operating System Zip ...

    • Other Actions in Bridge

      You can perform various additional actions from the Bridge page to manage, monitor, and troubleshoot your Bridge setup. To access the Bridge page: In Qntrl, click the settings gear icon in the left pane bottom. Navigate to Advanced >> Bridge and ...

    • Overview of Bridge

      What is a Bridge? Bridge is an installable, lightweight independent agent that can be deployed on the customer’s local network. It is compatible both on Windows and Linux machines with 64-bit OS. Its role is to facilitate communication between Qntrl ...

    • Bridge Agent Configuration

      The Bridge Agent serves is the local management console for your Bridge installation. It provides access to service configurations, execution logs, messages, credentials, and communication settings. The Agent UI is accessible only from within the ...

    • Troubleshooting FAQs - Data Transformation States

      1. When should I use a Data Transformation state instead of a Function state? Use Data Transformation states when the required logic can be achieved using built-in capabilities such as JSONata, JSLT, or dataset operations. This helps avoid custom ...