Troubleshoot Data Connectivity Proxy

Use these symptoms and resolutions when a Data Connectivity Proxy (DCP) agent or connector path isn’t working as expected.

Agent fails to start: token rejected

Symptom: The agent exits immediately with an authentication error.

Cause: The credentials file contains an opaque token (starting with PAT_) instead of a Snowflake Access JWT.

Resolution: Regenerate the token using SYSTEM$GENERATE_DATA_CONNECTIVITY_PROXY_BOOTSTRAP_TOKEN and write the output (not a PAT) to the credentials file.

Agent shows disconnected or down health

Symptom: DESCRIBE DATA CONNECTIVITY PROXY returns AGENT_HEALTH = DOWN, or AGENT_STATUS isn’t DCP_AGENT_LIFECYCLE_CONNECTED.

Steps:

  1. Check that the agent container is running: docker ps | grep dcp-agent
  2. Check agent logs: docker logs dcp-agent --tail 50
  3. Verify outbound port 443 is open from the agent host to <account>.snowflakecomputing.cn
  4. Run the agent health check (see Health check) to isolate which step is failing
  5. Check DCP_CLIENT_EVENT_HISTORY for EVENT_TYPE = 'BOOTSTRAP' or 'CONTROL_PLANE' rows with STATUS = 'FAILURE'. Check DESCRIBE for LAST_AUTH_FAILURE_REASON if authentication is failing.

Connector can’t reach a private source

Symptom: Connector connection attempts fail even though the agent is connected.

Steps:

  1. Verify the destination FQDN and port are covered by a HOST_PORT network rule with MODE = DATA_CONNECTIVITY_PROXY_EGRESS in the EAI associated with the DCP client
  2. Run DCP_CLIENT_ROUTE_CHECK for the destination as host:port
  3. Verify the agent host can reach the destination: docker exec dcp-agent nc -z <host> <port>
  4. Check firewall rules between the agent host and the data source

Bootstrap token expired before rotation

Symptom: DCP_CLIENT_EVENT_HISTORY shows EVENT_TYPE = 'CERT_ROTATION' with STATUS = 'FAILURE'. The agent is still running but can’t renew its certificates. DESCRIBE also shows CERT_ROTATION_STATUS as failed.

Resolution: The agent continues operating on its current certificates but can’t rotate them until a valid token is in place. Generate a new token and write it to the credentials file (see Rotate the bootstrap token without downtime). The agent picks it up on the next rotation attempt; no restart is required.

Multiple agents: some connections land on the wrong agent

Cause: DCP doesn’t load-balance individual connections across agents. Each workload-to-destination mapping is owned by exactly one agent at a time. Connections route deterministically through the control plane routing table.

Resolution: This is expected behavior, not a misconfiguration. For throughput scaling, size individual agent hosts appropriately. If a specific agent is saturated, review the EAI scoping so destinations are partitioned correctly across agents.