Portainer Agent Down Endpoint Diagnostic Guide

Portainer shows an endpoint Down even though Docker is running. This guide maps symptoms to causes for agent-managed hosts and gives ordered checks for container state, network reachability, and agent logs with tied fixes and escalation criteria.

If Portainer Environments shows an endpoint as Down or Unreachable while the Docker daemon on the target host is responding to docker info, the problem is almost always the Portainer Agent link, not Docker itself. The useful takeaway is to verify agent liveness first, then network reachability to the server, then registration logs, before changing TLS or firewall rules.

Recognizable condition

In the Portainer UI, Environments lists the managed Docker host with status Down or Unreachable. The host can still run containers, and docker ps works locally. For agent-managed endpoints, Portainer Server talks to the agent container on the host, which then proxies Docker API calls. An endpoint can be healthy on Docker but invisible to Portainer if the agent cannot register or be reached.

Cause to symptom mapping

Observed symptom	Likely cause
Endpoint Down, no recent heartbeat	Agent container stopped or crashed
Agent logs show connection refused / timeout	Incorrect AGENT_CLUSTER_ADDR or server URL, or DNS resolution failure
Agent logs show TLS handshake error or certificate verify failed	TLS certificate mismatch or expired self-signed certificate
curl from host to server succeeds but agent never registers	Host firewall blocking inbound TCP 9001 to the agent, or agent on wrong Docker network
Agent logs show successful registration but UI still Down	Server-side issue, database or proxy state

AGENT_CLUSTER_ADDR is the environment variable set on the agent container that points to the Portainer Server address. The agent listens on port 9001 for the server connection.

Ordered checks

Confirm agent container is running on the target host. Run as a user with Docker permissions on the target host:
```
docker ps | grep portainer_agent
```
Expected check: container state is Up. Risk: none. If no container appears, the agent is not deployed or was removed.
Test network reachability from host to Portainer Server. From the target host shell:
```
curl -v http://<server-hostname-or-ip>:9001
```
Replace <server-hostname-or-ip> with the address used in AGENT_CLUSTER_ADDR. Expected check: TCP connection succeeds. Risk: exposing credentials in shell history; use placeholders. Failure indicates routing, DNS, or firewall blocking outbound from host.
Inspect agent logs for registration errors. On the target host:
```
docker logs portainer_agent
```
Look for registration failures, connection refused, TLS handshake errors, or connection timeout messages. Required permissions: Docker read access. Risk: logs may contain internal URLs.

Fixes tied to findings

Agent container stopped. Restart the container with its current configuration. Verify restart policy is set to unless-stopped or always to avoid recurrence.
Incorrect server address. Update AGENT_CLUSTER_ADDR to the correct server URL and restart the agent container. Re-register the agent if the server URL changed.
Firewall blocking agent port. Open TCP 9001 inbound on the host firewall for the Portainer Server IP range only. Do not expose port 9001 to the public internet without a VPN or mutual TLS.
TLS mismatch. Re-add the endpoint in Portainer using the matching TLS setting, or replace the self-signed certificate used by the server. Changing an endpoint's TLS mode may require deleting and re-adding the environment; existing stacks and schedules are not moved automatically.
Wrong Docker network. Ensure the agent container is attached to the network that can reach the server. Recreate the agent with the correct network if needed.

Verification

After a change, confirm recovery in three places. In Portainer UI, open Environments and confirm the previously Down endpoint transitions to Up. On the managed host, run docker ps and verify portainer_agent is running with the expected restart policy. Review Portainer Server container logs for a successful agent registration event matching the target endpoint ID.

Escalation criteria

If agent logs show successful registration but the UI still shows Down, the issue is likely server-side. Collect Portainer Server logs and check server database or reverse proxy configuration. Contact Portainer support with endpoint ID, agent logs, and server logs. Do not modify server database manually.

Limitations and cautions

Portainer Community Edition and Business Edition differ in agent networking and edge agent defaults; verify your edition before applying firewall or certificate changes. The agent port is not a substitute for authenticated API access. Changing TLS mode requires re-adding the environment and may lose endpoint-specific metadata. This guide covers agent-managed endpoints; direct Docker socket connections have different failure modes.

Portainer Agent Endpoint Shows Down: Diagnostic Guide for Unreachable Docker Hosts