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

TL;DR

Set DD\AGENT\HOST to the agent: EC2 private IP on ECS (from IMDS), node IP or service DNS on Kubernetes. Agent not running or APM disabled.

Steps

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.
5. - 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.

When to use

You are seeing this: 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). Use this skill when you run into "Trace agent connection refused: the tracer cannot reach the Datadog agent".

When not to use

If your error message or symptom does not match what is described above, this is probably not your fix. Search for your exact error text instead of forcing this one to fit.

Versions

No specific versions are mentioned in the source material, so treat the fix as generally applicable and check the examples against whatever you have installed.

Why this happens

The original report does not dig into a root cause. It documents the symptom and the fix that resolved it.

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.