Skip to main content

Troubleshoot StackBob On-Prem Bridge

Troubleshooting · On-Prem Bridge

Written by Agent Bob

If you encounter difficulties setting up or running StackBob On-Prem Bridge, use this article to get it up and running. Find the issue that matches what you see in StackBob.ai, and then follow the troubleshooting steps.

Issue

What you see

What it means

Issue 1: The bridge stays in Bridge Pending

The node status remains Bridge Pending

The bridge has no connection to StackBob.ai. Either the bridge container is not running, or it cannot reach the StackBob.ai gateway.

Issue 2: The bridge is established, but the app cannot be reached

The node status is Bridge Established, but StackBob.ai reports host unreachable or TLS failed for the app

The bridge is connected to StackBob.ai. The remaining step is to make sure the bridge host can reach the managed app.

For bridge deployment steps, see Deploy a StackBob On-Prem Bridge. For security controls see StackBob On-Prem Bridge architecture and security.

ℹ️ The commands in this article use Docker. With Podman, use podman in place of docker. To find the bridge container ID, run docker ps -a.


Issue 1: The bridge stays in Bridge Pending

What you see

  • The node status remains Bridge Pending after the installation command is run.

What it means

  • StackBob.ai has not received a connection from the bridge. The status remains Bridge Pending until the bridge container is connected to the StackBob.ai gateway at bridge.stackbob.ai.

Possible causes

The bridge container is running but cannot reach StackBob.ai:

  • The host cannot reach bridge.stackbob.ai. See Fix 1A.

  • A proxy blocks or interrupts the connection. See Fix 1B.

  • TLS inspection interferes with the connection. See Fix 1C.

The bridge container is not running:

  • The token is invalid or has been revoked. See Fix 1D.

  • The host runs Windows containers only. See Fix 1E.

To find the cause, complete the checks in order:

  • Checks 1.1 and 1.2 confirm that the container is running.

  • Checks 1.3 to 1.6 confirm that the host can reach StackBob.ai.

  • Check 1.7 collects debug output for StackBob.ai support.

Each check ends with a table that explains each possible result and the next step.


Check 1.1: Container status

1.1.1. Find the bridge container:

bash

docker ps -a | grep stackbob-bridge

The output looks similar to the following:

CONTAINER ID   IMAGE                                           STATUS
3f2a9c1b7d4e public.ecr.aws/p2d9q2r4/stackbob-bridge:2.1.0 Up 2 hours

The container ID is the value in the first column. If more than one line is returned, use the first line, which is the most recently created container. If you mirrored the image to an internal registry under a different name, search for that name instead.
​
1.1.2. Store the container ID in a variable, and then display the container’s status, restart count, and exit code:

bash

BRIDGE=<container-id> docker inspect -f 'status={{.State.Status}} restarts={{.RestartCount}} exit={{.State.ExitCode}}' $BRIDGE


1.1.3. Wait one minute, run the docker inspect command again, and compare the results.

ℹ️ The later checks use the BRIDGE variable. The variable exists only in the current terminal session, and the container ID changes each time the container is recreated. If you open a new terminal or recreate the container, repeat steps 1.1.1 and 1.1.2.

Result

Meaning

Next step

Only the header line is returned in step 1.1.1

The bridge container does not exist on this host.

Run the installation command. See Deploy a StackBob On-Prem Bridge.

status=running, and the restarts count does not change

The container is running.

Continue to Check 1.2.

The restarts count increases, with exit=2 or exit=3

The bridge has a configuration problem, usually an invalid or revoked token. This is not a network issue.

See Fix 1D.

Any other status or exit code

The container is not running normally.

Continue to Check 1.2.


Check 1.2: Container logs

1.2.1 Save the most recent container logs to a file:

bash

docker logs --timestamps --tail 200 $BRIDGE > bridge.log 2>&1

1.2.2 Open bridge.log, for example with less bridge.log, and look for error messages. Compare what you find with the following table.

Result

Next step

The log reports a certificate or TLS error

See Fix 1C.

The log shows repeated connections and disconnections

See Fix 1B.

The log shows no clear error

Continue to Check 1.3.


Check 1.3: Proxy settings on the host

1.3.1 Display the proxy settings in the host environment:

bash

env | grep -i proxy

1.3.2 Compare the output with the following table.

Result

Meaning

Next step

No output

The host environment has no proxy configured. The connectivity tests in Checks 1.5 and 1.6 connect directly.

Continue to Check 1.4.

Proxy variables are printed

The host uses a proxy, and the connectivity tests in Checks 1.5 and 1.6 run through it. The bridge container does not inherit these settings.

Note the HTTPS_PROXY value. Confirm that the installation command includes the proxy, as described in Fix 1B. Then continue to Check 1.4.

ℹ️ A proxy that is configured only in a web browser does not appear in this output. If you are not sure whether your network requires a proxy for outbound traffic, ask your network team.


Check 1.4: DNS resolution

1.4.1 Resolve the gateway hostname:

bash

nslookup bridge.stackbob.ai

If nslookup is not installed, use getent hosts bridge.stackbob.ai instead.

1.4.2 Compare the output with the following table.

Result

Meaning

Next step

An IP address is returned

The host can resolve the gateway hostname.

Continue to Check 1.5.

The name cannot be resolved, and the host uses a proxy

This is expected in many proxied networks, because the proxy resolves external hostnames.

Continue to Check 1.5.

The name cannot be resolved, and the host does not use a proxy

The host cannot resolve the gateway hostname.

See Fix 1A.


Check 1.5: HTTPS reachability

1.5.1 Send an HTTPS request to the gateway:

bash

curl -sS --http1.1 --max-time 15 -o /dev/null -w '%{http_code}\n' https://bridge.stackbob.ai/connect

The expected output is 426. The gateway accepts only WebSocket connections, so it answers a regular HTTPS request with 426 Upgrade Required. This response confirms that the request reached the gateway.

1.5.2 Compare the output with the following table.

Result

Meaning

Next step

426

The host can reach the StackBob.ai gateway over HTTPS.

Continue to Check 1.6.

000 with a timeout or connection error, such as curl: (28) or curl: (7)

Outbound TCP 443 to bridge.stackbob.ai is not permitted.

See Fix 1A. If outbound traffic must pass through a proxy, see Fix 1B.

000 with a certificate error, such as curl: (60) SSL certificate problem

A TLS inspection device is re-signing the gateway certificate.

See Fix 1C.

Any other HTTP code, such as 403 or 407

A proxy or firewall in the path responded instead of the gateway.

See Fix 1B.


Check 1.6: WebSocket upgrade

1.6.1 Request a WebSocket connection from the gateway:

bash

curl -v --http1.1 --max-time 10 \   -H "Connection: Upgrade" -H "Upgrade: websocket" \   -H "Sec-WebSocket-Version: 13" -H "Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==" \   https://bridge.stackbob.ai/connect 2>&1 | grep -iE '^< HTTP|issuer|error'

The expected output looks similar to the following:

*  issuer: C=US; O=Let's Encrypt; CN=R11 < HTTP/1.1 101 Switching Protocols curl: (28) Operation timed out after 10001 milliseconds ...

The timeout on the last line is expected, because curl keeps the WebSocket connection open until the 10-second limit.

ℹ️ If the host uses a proxy, the output also includes a line such as HTTP/1.1 200 Connection established. This line comes from the proxy and is expected. Look for the 101 line after it.

1.6.2 Review the HTTP status line and the certificate issuer line, and compare them with the following table.

Line

Result

Next step

HTTP status

HTTP/1.1 101 Switching Protocols

The WebSocket upgrade works. Review the certificate issuer line.

HTTP status

Any other status, or no 101 line

A proxy or firewall does not permit the WebSocket upgrade. See Fix 1B.

Certificate issuer

Names Let’s Encrypt

The connection is not inspected. Continue to Check 1.7.

Certificate issuer

Names your organization or its CA

TLS inspection is active. See Fix 1C.


Check 1.7: Debug logging

If the previous checks did not identify the cause, run the bridge in the foreground with debug logging, and send the output to StackBob.ai support.

1.7.1 Remove the existing container:

bash

docker rm -f $BRIDGE

1.7.2 Start the bridge in the foreground with debug logging, and save the output to a file:

bash

docker run --rm --network host \   -e STACKBOB_TOKEN=<token> \   -e STACKBOB_DEBUG=1 \   public.ecr.aws/p2d9q2r4/stackbob-bridge:<version> 2>&1 | tee bridge-debug.log

Take the token and version from your installation command. The token is the value after STACKBOB_TOKEN=, and the version is the tag at the end, for example 2.1.0. If your installation command includes other options, such as a proxy, a CA certificate, or STACKBOB_TOKEN_FILE, include them as well.

1.7.3 Let the bridge run for about one minute.

1.7.4 Stop the bridge by pressing Ctrl+C.

1.7.5 Start the bridge again with your full original installation command, including all of its options. For example:

bash

docker run -d --restart=always --network host \   -e STACKBOB_TOKEN=<token> \   public.ecr.aws/p2d9q2r4/stackbob-bridge:<version>

1.7.6 Send bridge-debug.log to StackBob.ai support. See Get help from StackBob.ai support.


Fix 1A: Allow the host to reach bridge.stackbob.ai

1A.1 Ask your network team to make the following changes:

  • Allow DNS resolution of bridge.stackbob.ai from the host.

  • Permit outbound TCP 443 from the host to bridge.stackbob.ai.

1A.2 Repeat Check 1.4 and Check 1.5 to confirm the changes.

You do not need to restart the container, because the bridge retries the connection automatically. When the bridge connects, usually within a minute, the node status changes to Bridge Established.


Fix 1B: Configure the proxy for the bridge

The bridge container does not inherit the host’s proxy settings, and the proxy must allow the bridge’s long-lived WebSocket connection.

1B.1 Ask your network team to configure the proxy as follows:

  • Allow WebSocket connections to bridge.stackbob.ai:443.

  • Keep idle connections to bridge.stackbob.ai open for at least 30 seconds.

  • Do not buffer traffic to bridge.stackbob.ai.

1B.2 Remove the existing container:

bash

docker rm -f $BRIDGE

1B.3 Run the installation command with the proxy added:

bash

docker run -d --restart=always --network host \   -e HTTPS_PROXY=http://<proxy-host>:<port> \   -e STACKBOB_TOKEN=<token> \   public.ecr.aws/p2d9q2r4/stackbob-bridge:<version>

Use the same proxy address as the host, for example the HTTPS_PROXY value from Check 1.3. Most proxies use an http:// address, even though the bridge traffic itself is encrypted.

When the bridge connects, the node status changes to Bridge Established.

ℹ️ If the proxy requires authentication, contact StackBob.ai support.


Fix 1C: Resolve TLS inspection

A TLS inspection device is re-signing the gateway certificate with your organization’s CA, which the bridge does not trust by default. Use one of the following options.

Option 1 (recommended): Exclude the gateway from TLS inspection

Ask your network team to exclude bridge.stackbob.ai from TLS inspection. You do not need to restart the container, because the bridge retries the connection automatically.

Option 2: Trust your organization’s CA in the container

If inspection cannot be bypassed, mount your organization’s root CA certificate in the container. Your network or security team can provide the certificate. It must be in PEM format, which is a text file that starts with -----BEGIN CERTIFICATE-----.

1C.1 Save the certificate on the host, and make sure it is readable by all users, for example with permissions 644.

1C.2 Remove the existing container:

bash

docker rm -f $BRIDGE

1C.3 Run the installation command with the CA certificate added. Replace /path/to/corp-root.pem with the certificate’s location on the host:

bash

docker run -d --restart=always --network host \   -v /path/to/corp-root.pem:/certs/corp-root.pem:ro \   -e SSL_CERT_FILE=/certs/corp-root.pem \   -e STACKBOB_TOKEN=<token> \   public.ecr.aws/p2d9q2r4/stackbob-bridge:<version>

ℹ️ The bridge adds your CA to the public root certificates and does not replace them. Even when the inspection CA is trusted, the inspection device sees only encrypted tunnel traffic. The bridge pins the gateway’s key, so the device cannot impersonate StackBob.ai.

With either option, the node status changes to Bridge Established when the bridge connects.


Fix 1D: Replace an invalid or revoked token

The token is invalid or revoked if any of the following applies:

  • The node or its bridge group was terminated in StackBob.ai.

  • A newer installation command was generated for the node, which invalidated the previous token.

  • The token was copied incompletely, for example with a missing character.

1D.1 Remove the container:

bash

docker rm -f $BRIDGE

1D.2 In StackBob.ai, copy the node’s most recent installation command, and run it on the host.

1D.3 If the node was terminated, add a new node to the bridge group and run its installation command. If the bridge group was terminated, create a new bridge. See Deploy a StackBob On-Prem Bridge.

When the bridge connects, the node status changes to Bridge Established.


Fix 1E: Run the bridge on a host that supports Linux containers

Docker reports image operating system "linux" cannot be used on this platform when the host runs Windows containers only. Examples include Windows Server with Mirantis Container Runtime and Kubernetes Windows nodes. Use one of the following options:

  • Deploy the bridge on a Linux server or virtual machine, for example a Linux virtual machine on Hyper-V.

  • On Windows 10 or 11 with Docker Desktop, switch to Linux containers. Right-click the Docker icon in the system tray, and then select Switch to Linux containers.

  • If neither option is available, contact StackBob.ai to find a suitable deployment option.



Issue 2: The bridge is established, but the app cannot be reached

What you see

  • The node status is Bridge Established, but StackBob.ai reports that the managed app cannot be reached, with an error such as host unreachable or TLS failed.

What it means

  • The bridge is connected to StackBob.ai, so this part of the setup is complete. The remaining step is the connection from the bridge host to the managed app. The following steps help you confirm that the host can resolve and reach the app.

Possible causes

  • The app hostname does not resolve from the bridge host.

  • A firewall rule does not yet permit connections from the bridge host to the app.

  • The hostname or port configured for the app in StackBob.ai does not match the app.

  • The app uses a certificate issued by a private CA, which the bridge does not trust by default.

Resolution

2.1 From the host, confirm that the app hostname resolves through your internal DNS:

bash

nslookup <app-hostname>

2.2 From the host, confirm that the app is reachable on its port. If the app does not use TLS, use http:// instead of https://.

bash

curl -sv https://<app-hostname>:<port> -o /dev/null

2.3 Confirm that your firewall rules permit connections from the host to the app host and port.

2.4 The standard installation command uses --network host. If the bridge runs on a Docker network instead, confirm that internal DNS and routes are reachable from that network.

2.5 On macOS and on Windows 10 or 11, confirm that the app is reachable from the Linux virtual machine that Docker Desktop, Colima, OrbStack, or Podman provides.

2.6 If the error is TLS failed and the app uses a certificate issued by a private CA, contact StackBob.ai support. Support for internal CAs is available on request.

If the app is reachable from the host but StackBob.ai still reports an error, contact StackBob.ai support.


Get help from StackBob.ai support

If you need help at any point, contact StackBob.ai support at [email protected]. You do not need to complete every check first. The support team will work with you to get the bridge connected.

To speed up the resolution, include the following information where available:

  1. The bridge group name and node name, as shown in StackBob.ai

  2. The status line from Check 1.1

  3. bridge.log from Check 1.2

  4. The output of the commands in Checks 1.3 to 1.6

  5. bridge-debug.log from Check 1.7, if you ran it

⚠️ Do not send the installation command, the token, or the full output of docker inspect. They contain the token.


Related articles

Did this answer your question?