ECS Service Discovery DNS Not Resolving: Cloud Map Private Zones, Other VPCs, SRV-Only Bridge Mode, the .local Trap, Service Connect Names, TTL and Pricing

ECS service discovery DNS not resolving almost always means the name is being asked in the wrong place, in the wrong form, or before there is anything healthy to answer with. ECS service discovery is AWS Cloud Map writing DNS records for your tasks into a Route 53 private hosted zone, so api.shop.internal only answers inside the VPCs associated with that zone, only for the record type your network mode registered (A for awsvpc, SRV only for bridge and host), and only once a task is registered as healthy. Four checks find almost every case: the client is in another VPC or on premises; the VPC's DNS settings or a custom DNS server keep queries away from the Amazon resolver; the name, case or record type is wrong; or no task is healthy yet. Two surprises cause the rest. A namespace ending in .local is swallowed by multicast DNS on many Linux clients before it ever reaches AWS. And Service Connect names are not in DNS at all: they only work through the Service Connect proxy inside tasks that belong to the namespace. Below: the four commands that tell you which one you have, each cause with its fix, the stale-answer problem that looks like "connection refused," when to pick Service Connect or a load balancer instead, what Cloud Map costs, and a setup that works end to end.

Jake's booking app grew a second service in October: a small "receipts" API that the main web service calls after every payment. Ethan registered both in a Cloud Map namespace called shop.local and pointed the web service at http://receipts.shop.local:8080. From inside the web tasks it worked. From the EC2 bastion he used for testing, curl said Could not resolve host, and the Node.js admin script on the same bastion said getaddrinfo ENOTFOUND receipts.shop.local. "So it exists for the containers and not for the server next to them," Jake said. "Same network, same name. What's the difference?" The difference was the four letters at the end of the name.

New to the pieces? Our plain-English ECS guide covers clusters, tasks and services, and the hosted zone guide explains public and private zones. Commands below use the AWS CLI and dig; on Windows, nslookup works for the A-record checks and Resolve-DnsName -Type SRV for SRV records.

How ECS service discovery actually answers a name

When you turn on service discovery for an ECS service, ECS registers each task as an instance of a Cloud Map service inside a Cloud Map namespace. The namespace type decides how the name can be found:

With a private DNS namespace, a task in service receipts appears as records under receipts.shop.internal, pointing at the task's private IP. Traffic then goes straight from client to task: there is no load balancer in the path, and Classic Load Balancers are not involved at all. Which record types exist depends on the task's network mode, and up to eight healthy records are returned per answer. Every link in that chain is a place the lookup can fail, which is why the diagnosis below follows the chain.

"So Cloud Map is the receptionist who writes the room numbers down," Jake said, "and Route 53 is the noticeboard in the lobby." "A noticeboard in one particular lobby," Ethan said. "Stand in a different building and you can't read it."

Four commands that find the cause

Run these from a machine that should be able to resolve the name, ideally the one that fails. Replace shop.internal, receipts and the IDs with yours.

# 1. Does Cloud Map know about healthy instances? (bypasses DNS entirely)
aws servicediscovery discover-instances --namespace-name shop.internal --service-name receipts \
  --health-status HEALTHY --query "Instances[].Attributes"

# 2. Which record types did the service register, and with what TTL?
aws servicediscovery list-services --query "Services[?Name=='receipts'].[Id,DnsConfig]"

# 3. Can this VPC see the private hosted zone at all?
aws route53 list-hosted-zones-by-vpc --vpc-id vpc-0abc123 --vpc-region us-east-1 \
  --query "HostedZoneSummaries[].Name"

# 4. What does DNS actually say, from the failing machine?
dig +short receipts.shop.internal A
dig +short _receipts._tcp.shop.internal SRV
dig +short receipts.shop.internal SRV

Read your results in this order, and stop at the first one that matches:

1. Command 1 returns nothing? You have no healthy task to resolve, and DNS is behaving correctly. Go to no healthy instances.
2. Command 3 does not list your namespace? Your VPC cannot see the zone. Go to another VPC.
3. Command 2 shows only SRV, and your A query in command 4 is empty? Go to SRV only.
4. Commands 1 to 3 look right, but dig still says NXDOMAIN? Your question is not reaching the Amazon resolver, or you are asking for the wrong name. Go to DNS settings and the name.
5. dig answers, but your application cannot? Look at the .local trap and stale answers.

Ethan's bastion gave the telling result: dig receipts.shop.local answered with the task's IP, while curl and Node.js on the same machine failed. DNS worked; the machine's own resolver never asked it.

Cause 1: the client is in another VPC, on a VPN, or on premises

A private hosted zone answers only for queries that the Amazon resolver receives from a VPC associated with the zone. When you create a private DNS namespace, you pick one VPC, so if your client sits anywhere else, it gets NXDOMAIN, as if the name did not exist. This is your most likely cause when the failing client is not an ECS task in the same VPC: a Lambda function in a shared-services VPC, an EC2 instance in a peered VPC, your laptop on a Client VPN, or a server in your office.

Your fix depends on where the client lives:

1. Another VPC in the same account: associate the private hosted zone with that VPC. Peering or a Transit Gateway carries the traffic; the association is what makes the name resolve.

   ZONE=$(aws route53 list-hosted-zones-by-name --dns-name shop.internal --query "HostedZones[0].Id" --output text)
   aws route53 associate-vpc-with-hosted-zone --hosted-zone-id "$ZONE" --vpc VPCRegion=us-east-1,VPCId=vpc-0def456

2. A VPC in another account: the zone owner runs create-vpc-association-authorization for that VPC, then the other account runs associate-vpc-with-hosted-zone. The association can only be made from the CLI or API, not the console.
3. On premises or over a VPN: create a Route 53 Resolver inbound endpoint in the namespace's VPC and add a conditional forwarder for shop.internal on your office DNS servers, pointing at the endpoint's IPs. Our Client VPN DNS guide covers the laptop side, and the Resolver explainer covers inbound and outbound endpoints.

Remember that DNS only finds the address. The client still needs a network path to the task's private IP and a security group rule on the task that allows it, which is the subject of our VPC peering DNS guide.

Cause 2: the VPC's DNS settings, or a custom DNS server

Private hosted zones need two VPC attributes turned on: enableDnsSupport and enableDnsHostnames. With either off, the zone does not resolve inside the VPC, even for tasks in it. Check and fix them:

aws ec2 describe-vpc-attribute --vpc-id vpc-0abc123 --attribute enableDnsSupport
aws ec2 describe-vpc-attribute --vpc-id vpc-0abc123 --attribute enableDnsHostnames
aws ec2 modify-vpc-attribute --vpc-id vpc-0abc123 --enable-dns-hostnames "{\"Value\":true}"

The second version of this cause is a custom DHCP options set that hands your instances a DNS server of your own (your Active Directory controller, a Pi-hole, an old BIND box) instead of the Amazon resolver. Your server knows nothing about the private hosted zone unless it forwards the namespace to the Amazon resolver, which lives at the VPC CIDR base plus two (for 10.0.0.0/16, that is 10.0.0.2) and at 169.254.169.253. Add a conditional forwarder for the namespace on your DNS server, or let instances use AmazonProvidedDNS. An instance whose own resolver configuration was changed by hand, or by an agent that points it at a corporate DNS server, can fail while tasks in the same subnet succeed; compare /etc/resolv.conf on both.

Cause 3: the name is not quite the name

NXDOMAIN with everything else correct usually means you are asking for a slightly different name than the one registered. The registered form is service-name.namespace-name, with no cluster name, no task name and no trailing port:

• Service name, not ECS service name. The DNS label comes from the Cloud Map service name chosen when service discovery was set up, which is often, but not always, the ECS service name. list-services shows the real one.
• Namespace typos and leftovers. A service registered in shop.internal does not answer under shop.local, and an old namespace from a previous deployment may still exist next to the new one.
• Case collisions. DNS is case-insensitive, so services whose names differ only in case collide; give them distinct names.
• The wrong Region or account. Namespaces are Regional. A namespace created in us-east-1 does not answer for tasks in eu-west-1.

A quick way to see what really exists is to list the records in the hosted zone itself:

aws route53 list-resource-record-sets --hosted-zone-id "$ZONE" \
  --query "ResourceRecordSets[].[Name,Type,TTL]" --output table

Cause 4: bridge or host network mode registers SRV records only

The record types Cloud Map can register depend on the task's network mode, and this catches anyone moving between EC2 and Fargate:

On bridge mode, many of your containers share an instance and get random host ports, so an A record could not tell you which port to use; the SRV record carries both. Most HTTP clients, including curl and your browser, never look up SRV records, so they report "could not resolve" even though your name is registered. Either switch your service to awsvpc networking, which gives every task its own IP and an A record, or use a client that reads SRV records. For IPv6-only tasks, A records are not available; use AAAA.

Cause 5: no healthy instances to answer with

Cloud Map only returns healthy instances, so a name with nothing healthy behind it can look like a missing name. When ECS manages health for service discovery (the usual setup, a custom health check config on the Cloud Map service), tasks are registered as UNHEALTHY until their container health checks report a status, become HEALTHY when the checks pass, and are deregistered when they fail. So a service whose tasks keep failing their health check, or that is still starting, has nothing to put in DNS.

Command 1 from the diagnosis answers this for you directly; run it without --health-status to see your unhealthy instances too. If your list is empty, look at the ECS side: tasks that stop at startup, a health check command that does not exist in your image, or a start period that is too short for your app. Our ECS health check guide and the ResourceInitializationError guide cover the usual reasons tasks never turn healthy. One behavior to know: when every instance is unhealthy, Route 53 returns up to eight unhealthy records rather than nothing, so "it resolves to an IP that refuses connections" can also be this cause.

"So the noticeboard only lists rooms whose lights are on," Jake said. "And if every light is off," Ethan said, "it lists some of the dark ones anyway, which is somehow worse."

Cause 6: the .local trap on Linux clients

This was Ethan's bug. On many Linux systems, names ending in .local are reserved for multicast DNS (mDNS), the protocol printers and laptops use to find each other on a home network. systemd-resolved, Avahi and the mdns entry in /etc/nsswitch.conf send .local lookups to the local network segment instead of to the configured DNS server. The Amazon resolver never sees the question, so the private hosted zone never answers. dig talks to the DNS server directly, which is why it succeeds while curl, Node.js and Python, which use the system resolver, fail.

Your Fargate tasks are usually not affected, because typical container images do not run mDNS, which is exactly the "works in the container, fails on the server next to it" pattern. The clean fix is to give yourself a namespace that is not .local, such as shop.internal, and point your clients at the new names. Changing the namespace means creating a new one and updating your services, so plan it as a small migration. A stopgap on a single host is to adjust its resolver configuration so .local is not routed to mDNS, but you would need the same change on every new machine, which is why renaming wins.

# see whether this host routes .local to mDNS
grep hosts /etc/nsswitch.conf          # look for mdns4_minimal [NOTFOUND=return]
resolvectl query receipts.shop.local   # systemd-resolved's own view

Cause 7: you expected DNS from Service Connect

ECS Service Connect also uses Cloud Map, but differently. It creates the namespace with discovery set to API only and does not create any Route 53 hosted zone. The friendly names you configure (for example receipts:8080) work only through the Service Connect proxy that ECS adds to tasks in services that belong to that namespace. Outside that circle, including standalone tasks, EC2 instances, Lambda functions and your laptop, the names simply do not exist.

Three related details trip people up. Client services must be in the same Service Connect namespace and must be redeployed after a new endpoint is added, because the proxy learns endpoints when tasks start. Port mappings in the task definition need names, because Service Connect refers to them. And a new service can take a few minutes to pass its first health checks before traffic flows. If something outside ECS needs to call the service, add DNS service discovery (in a different discovery name from the Service Connect one, since the two cannot register the same name in the same namespace) or put a load balancer in front.

"It resolves, but the connection is refused": stale answers

A different failure looks similar: your name resolves, but to an IP where nothing is listening. Service discovery hands your clients task IPs directly, and those IPs change every time ECS replaces a task. If your client cached an old answer, it keeps connecting to a task that no longer exists until the cache expires.

• The record TTL. The TTL is set on the Cloud Map service's DNS configuration. A long TTL keeps old IPs in client caches after a deployment; a short one (such as 10 or 60 seconds) costs a few more queries. Our TTL guide explains the trade-off.
• Application caches. Some runtimes cache DNS answers on their own, independent of the TTL; the JVM is the best-known example, with a cache setting of its own. Connection pools that keep sockets open for hours never look the name up again.
• Retries. Clients should retry a failed connection with a fresh lookup, which also covers the brief window while a replaced task is deregistering.

This is where Service Connect is stronger: its proxy learns endpoint changes from ECS and does not depend on client DNS caches, and it retries and balances across tasks for you.

The remaining causes, briefly

Service discovery, Service Connect or a load balancer?

Once the name resolves, the real question is often whether DNS service discovery was the right tool. Here is how the three options compare for traffic between your services:

Many setups use more than one: Service Connect between ECS services, DNS discovery for the batch tasks and the bastion, and a load balancer at the front door. Questions comparing Cloud Map with Route 53 come down to this: Route 53 is the DNS service, and Cloud Map is the registry that keeps a service's records up to date as instances come and go, writing to Route 53 for DNS namespaces. Compared with tools such as Consul, Cloud Map is fully managed and integrated with ECS, but has fewer features such as a key-value store.

What Cloud Map costs

Cloud Map pricing has three parts, and for a small ECS setup the total is a few dollars a month:

• Registered resources: $0.10 per registered resource per month. Each running task registered in service discovery counts as a resource while it is registered.
• Discovery API calls: $1.00 per million DiscoverInstances calls, which matters for API-only discovery and for Service Connect proxies that refresh endpoints.
• DNS: a private DNS namespace is a Route 53 hosted zone, billed at Route 53 rates ($0.50 per month for each of the first 25 zones), and DNS queries are billed as Route 53 queries ($0.40 per million standard queries for the first billion a month).

Health checks for public namespaces are Route 53 health checks and are billed as such. There is no separate Cloud Map free tier, so a leftover namespace from a test keeps costing its hosted zone fee until you delete it.

A setup that works, end to end

This creates a private DNS namespace that avoids .local, a service discovery registry with A records and a short TTL, and an ECS service on Fargate that registers into it:

# 1. namespace (creates the private hosted zone in this VPC)
aws servicediscovery create-private-dns-namespace --name shop.internal --vpc vpc-0abc123

# 2. once the operation succeeds, get the namespace ID
NS=$(aws servicediscovery list-namespaces --query "Namespaces[?Name=='shop.internal'].Id" --output text)

# 3. Cloud Map service: A records, 10-second TTL, ECS-managed health
aws servicediscovery create-service --name receipts --namespace-id "$NS" \
  --dns-config "NamespaceId=$NS,RoutingPolicy=MULTIVALUE,DnsRecords=[{Type=A,TTL=10}]" \
  --health-check-custom-config FailureThreshold=1
SVC_ARN=$(aws servicediscovery list-services --query "Services[?Name=='receipts'].Arn" --output text)

# 4. ECS service (awsvpc networking) registering into it
aws ecs create-service --cluster shop --service-name receipts --task-definition receipts \
  --desired-count 2 --launch-type FARGATE \
  --network-configuration "awsvpcConfiguration={subnets=[subnet-0aa1,subnet-0bb2],securityGroups=[sg-0receipts],assignPublicIp=DISABLED}" \
  --service-registries "registryArn=$SVC_ARN"

# 5. test from a client in the same VPC
dig +short receipts.shop.internal

Read it against the causes: the namespace is .internal (cause 6); awsvpc networking gives A records (cause 4); the short TTL limits stale answers; the security group on the receipts tasks must allow the client's security group on port 8080; and any client outside this VPC needs the zone associated or a Resolver endpoint (cause 1). In Terraform the same pieces are aws_service_discovery_private_dns_namespace, aws_service_discovery_service and the service_registries block of aws_ecs_service.

Ethan created shop.internal, registered both services in it, changed one environment variable in the web service and one line in the admin script, and both answered from the bastion on the first try. He kept the old shop.local namespace for a week, then deleted it, because nobody else should ever have to learn about multicast DNS the way he did.

For IT admins: keeping service names resolvable

• Name namespaces .internal or after a domain you own, never .local, and keep one namespace per environment.
• Associate the private hosted zone with every VPC that needs it as part of the network template, and add a Resolver inbound endpoint for on-premises clients.
• Keep enableDnsSupport and enableDnsHostnames on, and forward the namespace to the Amazon resolver from any custom DNS server.
• Use awsvpc networking for services that others discover by name, so A records exist.
• Set short TTLs and client retries, and prefer Service Connect for chatty ECS-to-ECS traffic.
• Clean up Cloud Map services and namespaces when you delete ECS services, since they are not removed automatically.

Frequently asked questions

The receipts service has been answering by name ever since, from tasks, from the bastion and from the bookkeeper's report job. Jake wrote a single line on the team wiki under "naming": Nothing we build ends in .local. Ethan added a second: Check which building you are standing in.

Revision note. Written October 18, 2026. "A rose by any other name would smell as sweet," the proverb says; a service by any other name does not resolve at all.