# APM trace agent connection refused: the tracer cannot see the agent

Symptom: app runs, tracer initialized, zero traces in APM. The tracer log (or ddtrace-run --info, or the Node debug log) shows connection refused or timeouts to the trace agent endpoint.

## The mental model

Every tracer ships spans to the **Datadog agent** (its trace-agent component), defaulting to the same host. The agent then forwards to Datadog. So APM needs two hops working: app to agent, agent to Datadog. Connection refused is always hop one.

## Fix by environment

- **Same host**: should just work. If refused, the agent is not running or APM is disabled in its config. `datadog-agent status` first.
- **Docker / ECS / Kubernetes**: the loopback address inside your app container is NOT the agent. Set `DD_AGENT_HOST` to the agent container host: the EC2 private IP on ECS (from the instance metadata service), the node IP or a service DNS name on Kubernetes, the gateway IP or service name on plain Docker. The ECS docs show exactly this pattern for both DogStatsD and APM.
- **Full control**: `DD_TRACE_AGENT_URL` with the complete URL (scheme, host, port 8126). Useful for proxies and odd networks.
- **Lambda**: traces go through the Datadog extension, not a local agent. If you pointed the tracer at an agent host on Lambda, unset it.

## Confirm

From the app container/host, hit the trace agent port (default 8126) the way the tracer would. Then generate one request and watch the tracer debug log for a successful flush. In the app, APM Services should list the service within a minute or two.

## Traps

- Firewalls/security groups between app and agent subnets. The ECS docs warn about this: keep APM/DogStatsD ports off the public internet but open between your tasks.
- `DD_AGENT_HOST` set globally to a value that is right for one environment and wrong for another (staging vs prod). Per-environment config, not a shared default.
- Sampling confusion: connection works but no traces because the sample rate drops everything. That is a different skill (APM sampling), rule out connectivity first.