Skip to main content
Use this guide to quickly diagnose and resolve issues with your Traversal Connector.

​
Where to look first

  • The Connectors tab in the Traversal web app shows each Connector’s status and live metrics.
  • Integration connections. When several integrations that share a Connector fail at once, that Connector is the likely cause — even if it still shows Online.
The status alone often points to the problem:
  • Online — connected and working.
  • Waiting for connection — the Connector has never connected. This is normal right after you deploy, but if it persists, something is blocking the first connection.
  • Offline — the Connector connected before but has since dropped.
  • Active tunnels — the number of live connections. 0 means it isn’t connected.
  • Requests (last hour) and % successful — how much traffic ran, and how much of it succeeded.
One thing worth remembering: Online is not the same as healthy. A Connector can show Online while its success rate falls, which means it reaches Traversal but can’t reach something on your side.

​
Common issues

Several integrations on the same Connector start failing at once, often with NO_ACTIVE_TUNNEL or 503 errors. That error means the Edge Controller has no active tunnel for the Connector — it doesn’t say why.Open that Connector in the Connectors tab and check whether it’s Offline and whether its pods are running. The cause could be the Connector’s deployment, its certificate, a network route, or the Traversal control plane.
  • Run more than one Connector replica for extra capacity and headroom.
  • Keep the Connector on the latest version, since older versions can leave stale connections behind.
  • If the Connector looks healthy on your side and the errors continue, contact us with the errors you’re seeing and your Connector’s name.
The Connector can’t make its first connection, usually because its traffic is blocked or its identity is wrong.
  • Outbound traffic is blocked. Allow outbound access to both the controller URL and the telemetry endpoint shown in your deployment command — the controller uses HTTPS/mTLS, and telemetry uses OTLP/gRPC on port 4317.
  • You use a proxy or PrivateLink, but the route isn’t set up. Check your egress proxy, DNS, firewall, and PrivateLink route.
  • The controller URL is wrong. Copy it from Traversal exactly, with no extra path.
  • The connector ID is wrong or truncated. Copy the full ID and confirm it wasn’t cut short when your config rendered.
The Connector connected before, then dropped.
  • The certificate expired. Re-issue it, then redeploy.
  • You changed the certificate, but the pods kept the old one. Restart the Connector pods.
  • A deploy or GitOps sync removed something the Connector needs. Check what your last sync changed or pruned.
  • Your network or firewall changed. Confirm outbound HTTPS to Traversal is still allowed.
The Connector reaches Traversal but can’t complete the request to your system, so the tunnel stays up while one integration fails.
  • Traversal can’t trust your internal system’s certificate, and you see a certificate error. Add your internal CA chain.
  • The response is too large, or uses a format the Connector can’t read, so it gets dropped. Raise the size limit, or narrow where redaction applies.
  • One integration broke after an upgrade or on a specific request. Update the Connector to the latest version.
The Connector may be working, but Traversal sees no metrics from it.
  • The telemetry sidecar is enabled but not deployed. Deploy it, or switch to direct OTLP export.
  • Telemetry can’t reach Traversal. Check the OTLP settings, mTLS, and proxy route.
The container exits before it connects, and the status stays on ‘Waiting for connection’.
  • The certificate or key is missing or malformed. The startup log names the setting to fix.
  • The controller URL or connector ID is missing. Set both from Traversal.
  • The telemetry endpoints aren’t set. Set them, or turn telemetry off.
  • The image doesn’t match your CPU architecture. Pull the right build, such as ARM64.
  • Your registry can’t pull the image. Confirm your cluster can reach and authenticate to Docker Hub, set image.pullSecrets if needed, or mirror the image into an allowed internal registry. Pin a verified digest if your policy requires immutable references.

​
Still stuck?

If your issue isn’t listed here, or a fix didn’t work, email support@traversal.com or contact your Traversal representative. Include your Connector’s name and ID, what the health status shows, and — if you have them — the image digest and chart version.