Trace agent connection refused: the tracer cannot reach the Datadog agent

Trace agent connection refused at runtime

What you see: the app boots, the tracer initializes, and the tracer log fills with connection refused or dial tcp ... connect: connection refused pointing at the trace agent endpoint (port 8126 by default). APM stays empty.

Causes, in order

1. Containerized app, no DDAGENTHOST. The tracer defaults to the loopback address, which inside a container is the container itself. Set DD_AGENT_HOST to the agent: EC2 private IP on ECS (from IMDS), node IP or service DNS on Kubernetes.
2. Agent not running or APM disabled. On a bare host this should just work; if refused, datadog-agent status will show the trace agent missing or the process down.
3. Firewall/security group between app subnet and agent. The docs warn to keep the ports reachable from your workloads while off the public internet.
4. Wrong port/host override. Someone set DD_TRACE_AGENT_URL to a stale value. Unset it and let the default plus DD_AGENT_HOST do the job.

Fix

• From the app host/container, open a TCP connection to the agent on 8126 the way the tracer would. If that fails, it is network or agent, not tracer config.
• Set the right DD_AGENT_HOST, restart the app (tracer reads it at startup), generate one request.
• Watch the tracer debug log for a successful flush, then check APM Services.

Not this

If the connection succeeds but traces never appear, you have a sampling or site problem, not a connectivity problem. Connection refused is specifically hop one: app to agent.

The ECS docs document the pattern: app containers must reach the agent over the host network with DDAGENTHOST set to the EC2 private IP from IMDS, covering both DogStatsD and the trace agent endpoint; tracer setup docs default to a local agent with DDAGENTHOST / DDTRACEAGENT_URL as the overrides. Verified against live docs 2026-09-26.