Edge Agent connection problem.

[jeeey]

Ask a Question!

Hello everyone,

I’m having trouble connecting my Portainer Edge Agent (running in a private network) to my Portainer server (running on a public server). Here’s my setup and what I’ve tried so far:

Environment Details:

Portainer Server Version: ee-latest
Portainer Server Host OS: Ubuntu 22.04
Edge Agent Version: 2.19.1
Edge Agent Host OS: Rocky 9.5

Network Setup:
Portainer server has a public IP; firewall rules allow inbound on 8000 and 9443.
Edge Agent host is behind a NAT / private network, but outgoing connections on 8000 and 9443 are allowed.

What I Did:

Installed and started the Portainer server on the public machine using the usual Docker run command .
Deployed the Edge Agent on the private network host using the instructions from Portainer docs.
Verified via telnet that the private host can reach the public server on ports 8000 and 9443.

Observed Behavior:

Portainer web UI, the Edge Agent remains unreachable (but hearbeat is green).

In the Edge Agent logs I see:

2025/02/05 07:58PM DBG github.com/portainer/agent/chisel/client.go:37 > creating reverse tunnel client | local_addr=172.17.0.2:9001 remote_port=63738 server=x.x.x.x:8000 server_fingerprint=o
c74PbJBm8zOmoudsSA7qn3DiGtCupWgqH7xleULC4c=
2025/02/05 19:58:08 client: Connecting to ws://x.x.x.x:8000
2025/02/05 19:58:53 client: Connection error: read tcp 172.17.0.2:52460->x.x.x.x:8000: i/o timeout
2025/02/05 19:58:53 client: Give up

In the Portainer server logs I see:

2025/02/05 08:26PM DBG security/bouncer.go:402 > HTTP error | error="unable to open the tunnel" msg="Unable to get the active tunnel" status_code=500

Troubleshooting Steps Taken:

Checked firewall rules on the public server (port forwarding/open inbound on 8000, 9443).
Verified that the private network host can establish outbound connections on these ports.
Restarted both the Portainer container and the Edge Agent container.

Thanks in advance.

[Nick-Portainer]

Hi, in the Portainer UI Server do you see the edge environment showing that it has a heartbeat and it's when you click on the environment you get the error? The edge agent creates a tunnel on port 8000 so can you please run a telnet command from the agent to Portainer server and confirm it can connect?

[Nick-Portainer]

Hi @programmeryaml Can you confirm port 8000 is open on your Portainer Server? I can see from this 2025/02/05 19:58:53 client: Connection error: read tcp 172.17.0.2:52460->x.x.x.x:8000: i/o timeout that the connection is timing out, is your reverse proxy terminating the connection because it's exceeding the Proxy timeout?

[awcodify]

On my end, the port is open—telnet connects successfully. I also tried exposing port 8000 directly to the container and using a reverse proxy, but neither worked.

[dmit4git]

I may have the same issue. Heartbeat of my agent is green, telnet connection from agent to portainer over port 8000 works fine, but attempts to use the agent fail.

Portainer errors:

Apr 05 22:47:41 FX-6300 docker[3019453]: portainer  | 2025/04/06 01:47AM INF github.com/portainer/portainer/api/datastore/postinit/migrate_post_init.go:101 > Executing post init migration for environment 10 |
Apr 05 22:47:51 FX-6300 docker[3019453]: portainer  | 2025/04/06 01:47AM ERR github.com/portainer/portainer/api/datastore/postinit/migrate_post_init.go:121 > Error creating docker client for environment: 10 | error="unable to open the tunnel"
Apr 05 22:47:51 FX-6300 docker[3019453]: portainer  | 2025/04/06 01:47AM ERR github.com/portainer/portainer/api/pendingactions/handlers/post_init_migrate_environment.go:53 > Error running post-init migrations for edge environment 10 | error="unable to open the tunnel"
Apr 05 22:47:51 FX-6300 docker[3019453]: portainer  | 2025/04/06 01:47AM WRN github.com/portainer/portainer/api/pendingactions/pendingactions.go:115 > failed to execute pending action: failed running post-init migrations for edge environment 10: unable to open the tunnel |

Agent errors:

Apr 06 01:48:19 ip-172-31-32-237.ec2.internal docker-compose[35895]: portainer_agent  | 2025/04/06 01:48:19 client: Connecting to ws://containers.fullplate.dev:8000
Apr 06 01:48:19 ip-172-31-32-237.ec2.internal docker-compose[35895]: portainer_agent  | 2025/04/06 01:48:19 client: Connection error: websocket: bad handshake
Apr 06 01:48:19 ip-172-31-32-237.ec2.internal docker-compose[35895]: portainer_agent  | 2025/04/06 01:48:19 client: Give up

Regular agent (not edge) works ok.

[Unfaehig]

Running into the same issue.
Heartbeat is working, however websocket connection is never be successful.
Is it an problem, if portainer is running behind a reverse proxy? I see the edge server tries to connect via ws and not wss. Not sure if it expect a redirect to wss and therefore cut the connection? However than this seems to doesn't make sense: #6251

[Nick-Portainer]

Have you allowed Websockets within your Proxy?

[Nick-Portainer]

Can you confirm under your Edge settings that the API Server and Tunnel address is the correct address expected for the agent to be reaching?

[Lau-r-a]

Can you confirm under your Edge settings that the API Server and Tunnel address is the correct address expected for the agent to be reaching?

Can you confirm under your Edge settings that the API Server and Tunnel address is the correct address expected for the agent to be reaching?

I'm running into the same issue here

In the documentation theres no protocol at the tunnel server address: https://docs.portainer.io/admin/environments/add/docker/edge
Does it matter?

[rascal2018]

+1