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.
TLS handshake fails: certificate doesn’t match the DCP hostname¶
Symptom: DNS for dcp.<org>-<account>.<region>.<cloud>.snowflake.com resolves and TCP to port 443 succeeds, but the TLS handshake
fails. The server presents a certificate whose common name doesn’t match the DCP hostname, often *.privatelink.snowflakecomputing.com.
Cause: The agent is reaching a PrivateLink endpoint instead of the public DCP control plane.
Resolution: Confirm the agent uses the public DCP hostname from SYSTEM$ALLOWLIST, not a PrivateLink hostname or a PrivateLink DNS override. Connecting the DCP agent through a PrivateLink endpoint isn’t supported.
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:
- Check that the agent container is running:
docker ps | grep dcp-agent - Check agent logs:
docker logs dcp-agent --tail 50 - Verify outbound port 443 is open from the agent host to
<account>.snowflakecomputing.com - Run the agent health check (see Health check) to isolate which step is failing
- Check
DCP_CLIENT_EVENT_HISTORYforEVENT_TYPE = 'BOOTSTRAP'or'CONTROL_PLANE'rows withSTATUS = 'FAILURE'. Check DESCRIBE forLAST_AUTH_FAILURE_REASONif authentication is failing.
Agent can’t connect through a corporate proxy¶
Symptom: The agent is configured with a proxy but can’t bootstrap or connect to the relay. Agent logs show CONNECT
errors, TLS handshake failures, or a network policy rejection.
Steps:
-
On the agent host, list the names of proxy variables set in the container. The command doesn’t print their values or require tools inside the agent container:
If the proxy variable you expect isn’t listed, it isn’t set in the container. To check its value, inspect the container configuration privately. Proxy URLs can contain credentials; don’t share their values in tickets or screenshots.
-
Confirm the proxy allows
CONNECTto the control plane and relay destinations on port 443. See Route the agent through a corporate proxy. -
If the proxy URL starts with
https://, change it tohttp://, or setDCP_CONNECTION_MODE=direct-onlyand allowCONNECTto the relay’s public IP addresses. If the proxy only allowsCONNECTto hostnames, setDCP_CONNECTION_MODE=fallback-only. Inautomode, a rejected directCONNECTor TLS verification failure doesn’t trigger fallback. -
If the proxy inspects TLS, confirm that
SSL_CERT_FILEpoints to a bundle containing the proxy’s CA and thatDCP_CONNECTION_MODE=fallback-onlyis set. A hostname-based exemption fordcp-proxydoesn’t cover the direct relay path, which uses public IP addresses. See Inspect agent traffic. -
If
DCP_CLIENT_EVENT_HISTORYshows a failedBOOTSTRAPevent caused by a network policy, allow the proxy’s egress IP address in the network policy.
Connector can’t reach a private source¶
Symptom: Connector connection attempts fail even though the agent is connected.
Steps:
- Verify
DESCRIBE DATA CONNECTIVITY PROXYlists the EAI inEXTERNAL_ACCESS_INTEGRATIONS. If it’s empty, associate the EAI withALTER DATA CONNECTIVITY PROXY ... SET EXTERNAL_ACCESS_INTEGRATIONS. - Verify the destination FQDN and port are covered by a
HOST_PORTnetwork rule withMODE = DATA_CONNECTIVITY_PROXY_EGRESSin that EAI - Confirm the same EAI is attached to the Openflow runtime
- Run
DCP_CLIENT_ROUTE_CHECKfor the destination ashost:port - Verify the agent host can reach the destination:
docker exec dcp-agent nc -z <host> <port> - 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.