Why Does a Compose Network Alias Stop Resolving After the Stack Is Recreated Under a New Project Name?
A Compose alias can stop resolving after recreation when the service joins a different project-scoped network or the alias is no longer attached there.
Docker aliases are network-scoped, not global names. Recreating a stack under a new directory, explicit project name, Portainer stack name, or Compose project can create a new default network while another app remains on the old one. The service may be healthy and reachable by published port, yet its internal alias fails because the caller and target no longer share the same network or because a reverse proxy selected a different attachment.
Compare the Old and New Compose Project Names
Record the previous and current project name, working directory, stack name, network names, and container labels. Compare the caller and target service after recreation.
Docker Compose uses the project name to group and name resources. Its project-name precedence explains why changing the directory or deployment name can create a new network instead of reusing the old project network.
If the caller remains attached to oldproject_default while the target joins newproject_default, the former alias has no shared DNS scope.
Verify the Alias on the Exact Shared Network
Inspect both containers and list every attached network, endpoint, IPv4 or IPv6 address, and alias. Test DNS from inside the caller container.
The Compose specification defines aliases as network-scoped names, so an alias declared under one network does not automatically exist on another attachment.
Move the alias declaration to the network actually shared by the services. Do not rely on container_name as a replacement for deliberate service discovery.
Check External Network Names and Deployment Substitution
Compare the logical Compose network key with its explicit external name. Check environment substitution and stack UI variables used during deployment.
Portainer documents that stacks can use existing Docker networks, which must be selected consistently when independently deployed stacks need to resolve each other.
An external network prevents project-prefix changes only when every stack references the same actual network name. A typo can create or select a different network without changing the service’s published port.
Confirm the Caller Uses Docker DNS Rather Than a Cached Address
Run a fresh lookup from the caller, inspect its resolver configuration, and restart only the process that caches DNS when necessary. Compare name resolution with direct service-name lookup.
The Linux network-namespace model isolates network resources, which is why host DNS success does not prove the caller container shares the target’s Docker network.
Do not add the target’s current container IP to /etc/hosts. Recreated containers can receive a different address, leaving another stale dependency.
Check Which Network the Reverse Proxy Uses
Inspect proxy and application network attachments, provider labels, and the network selected for backend routing. Test the alias from the proxy container.
Traefik’s Docker provider supports specifying the Docker network used for backend connections.
If the proxy is attached to several networks, automatic selection can differ after recreation. Set the intended shared network explicitly and keep its actual name stable.
Remove Stale Endpoints Without Deleting the Wrong Network
List connected containers on the old and new networks. Identify orphaned endpoints, stopped containers, and active services that still depend on the old project network.
Red Hat’s container networking guide describes user-defined container network attachment as part of the container runtime state rather than application file content.
Remove an old network only after proving no active stack uses it. Deleting both networks and recreating everything at once destroys the evidence showing which attachment was wrong.
Recreate One Service and Verify DNS From Every Caller
Standardize the project name or external network, recreate only the affected service, and test service name and alias from each dependent container.
The ZimaSpace article on container runtime dependencies provides the adjacent rule: a host-level connectivity test does not validate a container’s namespace and service-discovery path.
The issue is resolved when the alias resolves to the current endpoint from every intended caller after stack recreation and reboot, without hard-coded IP addresses.
Frequently Asked Questions
Are Docker network aliases global?
No. An alias exists only on the network where it is configured and is useful only to containers that share that network.
Can changing the Compose folder name break DNS?
Yes. The folder can affect the default project name, which affects generated network names unless the project or external network name is fixed.
Should I use container_name to keep DNS stable?
Usually no. Stable service names and explicit shared networks preserve Compose scaling and avoid global-name collisions.
Recommended products
Support & Tips
More to Read
Why Does a Docker Volume Restore Recreate File Contents but Drop Extended Attributes?
A volume-restore diagnosis covering xattr inventory, tar and Rsync options, namespaces, destination support, privileges, labels, app metadata, and tests.
Why Does a Running Container Keep Its Old Memory Limit After the Compose File Changes?
A memory-limit diagnosis covering live cgroups, restart versus recreation, Compose fields, hard and soft limits, parent scopes, swap, and runtime heaps.
Why Does Restarting a Reverse Proxy Invalidate Every Session for One Self-Hosted App?
A session-loss diagnosis covering restart scope, cookie ownership, secret rotation, cache-backed sessions, sticky routing, auth gateways, and recovery.
