If your tests pass locally but fail in the cloud over mabl Link, or you see an error such as ERR_TUNNEL_CONNECTION_FAILED, "Unable to find active mabl link tunnel", or "No Link Agent is connected for tunnel", the Link Agent or the network around it usually needs attention. This article covers the most common symptoms, what causes them, and how to fix them. Choose the symptom that matches what you see:
- The Link Agent won't start
- The Link Agent doesn't connect to mabl
- Tests can't find a connected Link Agent
- Tests can't reach the application
- Tests over Link are slow or fail under load
- Access to a tunnel is denied
- A Link Agent stopped on its own
For tools that test a tunnel directly, see Testing and diagnosing Link connections.
The Link Agent won't start
The API key or tunnel name can't be used. The Link Agent checks both when it starts and reports the problem instead of retrying. Make sure that:
- The API key is a "Link Agent" API key, from Settings > APIs for a workspace tunnel or from the company dashboard for a company tunnel.
- The tunnel name is 1 to 24 characters of lowercase letters, numbers, and dashes. Capital letters and underscores are not allowed.
- A configuration file copied from an example has been edited. The placeholder API key and tunnel name in the examples can't be used.
The Java version is too old. If you see unrecognized option: --add-opens, the host runs a Java version older than 11. Install Java 11 or later, or use the Windows installer or the Docker image, which include their own Java runtime. See Link Agent requirements.
The platform isn't supported. The Link Agent runs on Linux (x86-64 and arm64), macOS on Apple silicon, and Windows on x86-64. Move an agent on a Mac with an Intel processor or on Windows on ARM to a supported platform.
The command isn't found. If you see Bad command or file name or command not found, run the command from the Link Agent's installation directory, for example bin/link-agent.
The Link Agent doesn't connect to mabl
While a Link Agent starts, its status on Settings > Networking moves through Initializing agent, Initializing tunnel, Announcing, and Securing tunnel, and it should reach Connected within a minute or two.
The host can't reach mabl's Link endpoints. If the agent stays on Initializing tunnel or Securing tunnel, or the Endpoint column shows a warning that the agent "cannot reach mabl … over UDP or … over TCP", the host can reach api.mabl.com but not the tunnel endpoints. Allow outgoing connections to one of the tunnel endpoints in Link Agent requirements. The agent needs only one of them.
A proxy sits between the agent and mabl. QUIC can't pass through an HTTP proxy, so an agent behind a proxy connects over WSS. Make sure the proxy allows the WSS endpoint, and that the agent's proxy settings are correct. See Forward proxies for mabl Link traffic.
The agent can't reach api.mabl.com. If the agent never appears in the Agents table, it can't reach api.mabl.com, or it connected earlier and has since stopped sending heartbeats. Check Recent activity at the bottom of the networking page for a disconnect, then check the agent's logs.
To test the connections from the agent's host:
curl -sS -o /dev/null -w "%{http_code}\n" https://api.mabl.com
nc -vz {wss-endpoint} 443
Test-NetConnection api.mabl.com -Port 443
Test-NetConnection {wss-endpoint} -Port 443
Replace {wss-endpoint} with the WSS endpoint from Link Agent requirements. For api.mabl.com, any HTTP status code means the host reached it. For the WSS endpoint, a successful TCP connection means the host can reach the tunnel endpoint. A timeout or a failed name lookup means something on the network blocks the address. These tools can't test the QUIC endpoint over UDP, so rely on the Endpoint column for QUIC. If the agent's host sends its traffic through an HTTP proxy, test through the proxy instead, or check the Endpoint column.
If a firewall or proxy blocks the addresses, ask your networking team to allow them.
Tests can't find a connected Link Agent
Test output shows "No Link Agent is connected for tunnel" followed by the tunnel name, or "Unable to find active mabl link tunnel".
No agent is connected to the tunnel the environment uses. Go to Settings > Networking and check the Tunnels table:
- Agents shows how many agents are connected to each tunnel. A tunnel with no connected agent can't carry tests. Start an agent on it, and see The Link Agent doesn't connect to mabl if it won't connect.
- Environments lists the environments that route through each tunnel. If the environment your test uses is missing, or uses a different tunnel name than your agent, update the environment's Link Agent settings.
An environment configured to use mabl Link
The agent is in maintenance mode. An agent whose status is Draining or Drained doesn't take new connections. If it is the only agent on its tunnel, exit maintenance from its Manage menu. See Maintaining and updating Link Agents.
The agent was disconnected during the run. Check Recent activity on the networking page, or the activity feed, for a disconnect that lines up with the time of the failing run. In the Agents table, Last connection shows when the agent most recently connected. An agent that loses its connection reconnects on its own without restarting.
Common reasons a Link Agent stops running:
- The host rebooted, or the user who started the agent logged out. Run the agent as a service so that it keeps running and starts with the host. See Link Agent setup.
- The host ran out of memory. See Tests over Link are slow or fail under load.
Tests can't reach the application
The Link Agent is connected, but tests time out, can't resolve the application's name, or get a connection error.
The agent's host can't reach the application. DNS resolution and connections happen on the Link Agent's host, so the host must be able to reach everything the application under test uses. Test from the tunnel itself:
- In the mabl desktop app, run Reachability, TCP connect, or HTTP request in Link tunnel diagnostics.
- In the mabl CLI, run
mabl link-agents test url {url} --tunnel {name}ormabl link-agents test tcp {host:port} --tunnel {name}.
If the check fails, the network where the agent runs doesn't allow the connection. You can also sign in to the agent's host and use curl against the application.
Agents on the same tunnel see different networks. If a test passes sometimes and fails at other times, the agents on its tunnel may not all reach the application, or may resolve its name to different addresses. Run mabl link-agents test destination {host:port} --tunnel {name}, which compares every agent, or choose Every agent in the desktop diagnostics. Fix the host that differs, or move it to its own tunnel.
A connection filter blocks the target. If the Connections by outcome chart on the networking page shows Blocked by connection filter, the agent's connection filter doesn't allow the destination. Add it to the filter.
The application is on the agent's own host. To test localhost, see Testing localhost with mabl Link.
Tests over Link are slow or fail under load
Tests pass when few run at once, but slow down or fail during busy plan runs.
The agent's host is short of CPU or memory. Check the Health column in the Agents table and the Warnings count at the top of the networking page. Open the agent's details to see which resource is short under Live capacity & host health and Host tuning & sizing. An agent shows a warning once a host resource passes 80%, and a critical status past 90%.
To fix it, give the host more CPU or memory, or add Link Agents with the same tunnel name on other hosts to share the load. See Sizing and scaling Link Agents.
The host's socket-buffer limits haven't been raised. The default limits cap tunnel throughput, most noticeably when the agent is far from mabl. Raise them as mabl recommends. See Raise the host's socket-buffer limits.
Access to a tunnel is denied
The mabl desktop app or CLI shows You do not have access to this tunnel, or "Access denied", when you train a test over Link or run diagnostics.
Your role isn't allowed to reach the tunnel. A workspace owner, or a company admin for a company tunnel, must add your role under Link tunnel access. See Controlling access to Link tunnels.
Personal tunnels are turned off. If you can't start a personal tunnel, a workspace owner must turn on Allow personal Link tunnels. See Personal Link tunnels.
A Link Agent stopped on its own
The API key was revoked. When mabl reports that a tunnel's API key is no longer valid, the Link Agent stops that tunnel instead of retrying. Create a new "Link Agent" API key, update the agent's configuration, and start it again.
The account's access to mabl Link ended. When a workspace or company can no longer use mabl Link, most often because a trial expired, the Link Agent logs the following and stops that tunnel:
Link is not enabled on your account, or your account is inactive for tunnel "{tunnel-name}"
Once no tunnel is left running, the agent exits. By design, it doesn't reconnect by itself after the account is active again, and the services the installers set up leave it stopped after this kind of exit. Once the account is active again, start the Link Agent:
| Installation | What to do |
|---|---|
| Linux, with the installer | sudo systemctl start mabl-link-agent |
| macOS, with the installer | sudo launchctl kickstart system/com.mabl.link-agent |
| Windows installer | Start the mabl Link Agent service in Services, or run sc start MablLinkAgent from an elevated command prompt. |
| Docker | If the container stopped, run docker start mabl-link-agent, using your container's name. With --restart unless-stopped, Docker starts it again by itself, and it reconnects once the account is active. |
| Kubernetes | Kubernetes restarts the container by itself, and it reconnects once the account is active. To reconnect sooner, delete the pod. |
| mabl CLI or a terminal | Start the agent again. |
If the Link Agent also serves tunnels for other workspaces, it keeps running for those. Restart it to bring the reactivated tunnel back, for example with sudo systemctl restart mabl-link-agent on Linux, sudo launchctl kickstart -k system/com.mabl.link-agent on macOS, or by restarting the mabl Link Agent service on Windows.
The agent was shut down from mabl. An agent shut down from the Manage menu or with mabl link-agents terminate stops and does not reconnect. Check the activity feed to see who shut it down.
Find the Link Agent logs
The Link Agent's logs explain why it disconnected or stopped. Where they are depends on how you installed it:
| Installation | Logs |
|---|---|
| Linux and macOS installer |
logs/agent.log under the installation directory, by default /opt/mabl/link-agent/logs/agent.log. On Linux, also journalctl -u mabl-link-agent. |
| Windows installer |
C:\ProgramData\mabl\link-agent\logs, or the logs folder in the data folder you chose |
| zip or tar.bz2 archive |
logs/agent.log under the directory where you extracted the agent |
| Docker | docker logs {container-name} |
| Kubernetes | kubectl logs {pod-name} -n {namespace} |
| mabl CLI | The log directory the CLI prints when the agent starts, which holds a link-agent log and a link-worker log for each tunnel |
Reach out to the mabl team
If you still can't find the cause, contact mabl. Include:
- The tunnel name and the Link Agent ID from Settings > Networking
- The time window of a failing run, with a link to the run
- The Link Agent logs from that time
- What your diagnostics checks returned, if you ran any
To let mabl run checks through your tunnel while they investigate, turn on support access for the workspace or company that owns it.