Portainer Agent Shows Down: Connectivity Diagnostic Guide

The Problem: Agent Running, Environment Down

A Docker, Linux, or Kubernetes environment added through the Portainer Agent can show Down or Agent disconnected in the Portainer UI even though the agent container is running on the target host. The useful takeaway is that this is usually a reachability or trust problem between the agent and Portainer Server, not a missing agent process. Start by confirming the agent container is up, then verify network and certificate alignment before changing server configuration.

Cause and Diagnostic Table

Observed condition	Likely cause	Where to confirm
Agent container running; UI shows Down	SERVER_URL does not match the reachable Portainer Server base URL	Agent stack environment; Portainer endpoint URL
Agent logs show dial or connection-refused errors	Firewall or cloud security group blocks agent-to-server or server-to-agent TCP port	Host firewall; cloud console security group
Agent logs show TLS handshake or x509 errors	Self-signed or mismatched TLS certificate on Portainer Server	Portainer Server certificate; agent trust store
Server cannot reach agent host	Agent attached to a Docker network that cannot route to the server, or AGENT_ADDR is wrong	Agent network settings; endpoint address
Intermittent or all-agent failures	Server certificate, reverse proxy, database, or major-version mismatch between agent and server	Portainer Server logs; infrastructure logs

Ordered Checks

1. Check agent container logs

   Run on the agent host. You need membership in the docker group or sudo.

   docker logs --tail 100 <agent-container-name>

   Replace <agent-container-name> with the actual agent container name, such as portainer_agent. Look for lines mentioning dial, connection refused, TLS handshake, or x509. Absence of errors does not prove connectivity.

   Risk: Logs may contain endpoint addresses or registration tokens. Do not share unredacted logs publicly.

2. Probe the Portainer Server port from the agent host

   Run on the agent host. No special permissions are usually required for an outbound probe.

   nc -vz <server-host> <server-port>

   Replace <server-host> with the Portainer Server hostname or IP and <server-port> with the port in SERVER_URL. Common defaults include 9000 for HTTP and 9443 for HTTPS in Portainer CE, but ports differ by edition and major version; verify against your release notes. Expected output indicates the port is open. A timeout means egress is blocked or the address is wrong.

3. Probe the agent port from the Portainer Server host

   Run on the Portainer Server host. You may need sudo to inspect local listening sockets or firewall rules.

   nc -vz <agent-host> <agent-port>

   Replace <agent-host> with the agent host IP or DNS name and <agent-port> with the port from AGENT_ADDR. A common agent listener port is 9001, but confirm your installed version. Expected output indicates the port is open. A timeout means ingress is blocked or the agent is not listening on that interface.

4. Compare SERVER_URL, AGENT_ADDR, and the Portainer endpoint

   Run in the Portainer UI and on the agent host. You need Portainer administrator access and docker or sudo on the agent host.

   Open Settings > Endpoints, select the affected endpoint, and compare its URL with the SERVER_URL value in the agent stack. The scheme, host, and port must match exactly and be resolvable from the agent host. Also confirm AGENT_ADDR is set to an interface the server can reach, not 127.0.0.1 unless the server runs on the same host.

5. Inspect Portainer Server logs

   Run on the Portainer Server host with docker or sudo access.

   docker logs --tail 100 <portainer-server-container>

   Replace <portainer-server-container> with the actual container name. Look for failed agent handshake or authentication entries. If every agent reports failures at the same time, the issue is likely server-side rather than network-specific.

Fixes Tied to Findings

1. Correct SERVER_URL and AGENT_ADDR

If the endpoint URL in Portainer is https://portainer.example.com:9443, set SERVER_URL to exactly that value in the agent stack. Do not add a path unless your Portainer deployment requires it. Set AGENT_ADDR to the agent interface reachable by the server, for example 0.0.0.0:9001 or a specific host IP. Redeploy the agent stack after editing.

version: "3.8"
services:
  agent:
    image: portainer/agent:<pinned-tag>
    environment:
      SERVER_URL: "https://portainer.example.com:9443"
      AGENT_ADDR: "0.0.0.0:9001"
    ports:
      - "9001:9001"

Replace <pinned-tag> with the agent image tag matching your Portainer Server release. Avoid latest in production because agent and server major versions should be compatible.

2. Open firewall and security group rules

Allow inbound TCP to the Portainer Server port from agent hosts, and inbound TCP to the agent port from the Portainer Server host. In cloud environments, update the security group associated with each instance; on Linux hosts, check iptables, nftables, or the distribution firewall. Test again with the nc probes above after changes.

3. Resolve TLS certificate errors

If agent logs show TLS handshake or x509 errors, the agent does not trust the Portainer Server certificate. Add the server CA certificate to the agent trust store using the method for your Portainer edition and version, or replace the server certificate with one signed by a trusted CA. Do not disable TLS certificate verification in production solely to clear connection errors; it exposes traffic to interception.

4. Fix routing or endpoint address

If the server cannot reach the agent, move the agent to a Docker network that routes to the server host, or change the Portainer endpoint URL to an address the server can reach. Avoid binding the agent to 127.0.0.1 when the server is on a different host.

Rollback After Redeploy

Changing agent environment variables and redeploying the stack changes state. Before editing, copy the current stack file or record the output of docker stack ps or docker service ps. To rollback, restore the previous environment values and redeploy the stack. The agent should return to its prior connectivity state. Leave newly opened firewall rules in place if they were previously missing.

Escalation Criteria

Escalate to the platform team or support channel if:

• Connectivity remains down after network checks and environment corrections.
• All agents fail at the same time, which suggests a server certificate, reverse proxy, load balancer, or database issue.
• Agent and Server major versions are mismatched and registration fails silently.

Collect agent logs, Portainer Server logs, and packet-capture output from the network path before escalating.

Limitations and Verification

Portainer CE and Business Edition use different default ports and agent behavior, and behavior changes across major versions. Verify all ports, image tags, and certificate steps against your deployed release. This guide is a draft for human review; confirm commands and paths in your environment before applying to production.

Practical check: deploy a test agent stack with explicit SERVER_URL and AGENT_ADDR values, then confirm the environment status turns Up in the Portainer UI within a few minutes. Use nc -vz in both directions and check docker logs for a successful registration message and no repeated TLS handshake errors.