DOCUMENTATION

The connector shows offline

The install command ran, but the console never shows Online — or it was online and dropped.

Symptom

Under Infrastructure → Connectors the connector stays Offline or shows Pending pairing. Vendors opening a resource routed through it get a 502. A connector that used to be online may show a Last seen time that stopped advancing.

Check these first

  1. On the machine that runs it, read the connector's own log: docker logs --tail 50 access-connector. Almost every cause on this page names itself there.
  2. Check that all three containers are up: docker ps should list access-connector, captivo-guacd and captivo-kasm.
  3. From the same machine, confirm the tunnel address answers over HTTPS: curl -sI https://connect.cloud.captivo.io on Cloud, or curl -sI https://connect.access.<your-domain> on your own server.

Possible causes

Wrong tunnel address (ws instead of wss)

How to tell: The log complains about the dial to DATAPLANE_URL: a refused connection, a TLS error, or a plain-text ws:// address being rejected. The console shows the connector as never seen.

Fix: The tunnel address must start with wss:// and point at the connect host: wss://connect.cloud.captivo.io on Cloud, wss://connect.access.<your-domain> on your own server. A ws:// tunnel would carry traffic unencrypted and is refused. Do not hand-type the command; copy it again from Infrastructure → Connectors, where it comes pre-filled (see running the command).

The machine cannot reach port 443 outbound

How to tell: The curl check above hangs or fails, and the log shows timeouts rather than refusals. The machine sits behind a corporate proxy or an egress firewall that allows only listed destinations.

Fix: The connector needs nothing inbound, but it does need outbound TCP 443 to two names: the tunnel host (connect.…) and the console (MANAGER_URL). Ask the network team to allow both from the connector host. A proxy that inspects TLS will break the WebSocket tunnel; exempt these two hosts from inspection.

The pairing code was used or has expired

How to tell: The log reports that enrollment failed or the pairing code was rejected. Typically the command was run a second time, on a second machine, or days after it was copied.

Fix: A pairing code works exactly once. Open the connector under Infrastructure → Connectors, press Re-pair to get a fresh command, and run that one. If you wanted a second connector, add a new one instead; each has its own code and its own token volume.

The data volume was lost and the token with it

How to tell: A connector that was online went offline after someone recreated the container. The log says there is no stored token and no pairing code to enroll with.

Fix: The token lives in the access_connector_data volume at /data/token. A docker rm without that volume, or a run command naming a different volume, loses it. Re-pair from the console and keep the volume name from the console's command. Note that the same volume holds the session recordings and recording.key; if it is gone, so are they (see data directory and backup).

One of the containers is not running

How to tell: docker ps shows fewer than three containers. If access-connector itself is missing, the console says Offline. If only captivo-guacd or captivo-kasm is missing, the connector stays Online but remote-desktop or isolated-browser sessions fail.

Fix: Start the stopped container with docker start <name> and read its log for the reason it exited (out of disk, a port clash on the host, a kernel without the needed features). If a container was removed, run the console's install command again; it recreates all three on the shared network. For engine-only problems see remote desktop session does not connect.

Outdated version

How to tell: The connector carries an Outdated badge in the console. After a console upgrade an old connector may still connect but refuse newer control messages, or drop and reconnect repeatedly.

Fix: Pull the current image and recreate the container: docker pull ghcr.io/captivo-io/captivo-access-connector:latest, then the recreate command shown under Infrastructure → Updates. The token in the volume persists, so no re-pairing is needed (see updating). While you are there, check the host clock: a clock that is minutes off breaks the TLS handshake.

For per-request detail, open the connector's page and set Logging to Debug; the Recent logs tail then shows every dial. Turn it back to Info when done.

If it is still not solved

  • The last 50 lines of docker logs access-connector
  • The output of docker ps on the connector host
  • The result of the curl check against the connect address
  • Whether the host sits behind a proxy or TLS inspection
  • The connector's version shown under Live telemetry

Was this article helpful?