Docker Swarm: How to Fix “error creating vxlan interface: file exists”

Docker Swarm relies heavily on Overlay networks to provide communication between services running across different nodes.

One networking issue that can occasionally occur after a node restart, Docker restart, network disruption, or other changes to the Docker networking state is a service repeatedly failing to start with an error similar to:

network sandbox join failed:
subnet sandbox join failed for "10.0.0.0/24":
error creating vxlan interface: file exists

The error can be misleading. The affected service may be perfectly healthy, and the Swarm network configuration may also be correct.

In some cases, the actual problem is a stale VXLAN interface left on the affected node.

This article explains how to diagnose this situation and safely resolve it.

The Symptom

Suppose a Swarm service named example_gateway is repeatedly rejected:

docker service ps --no-trunc example_gateway

The output may look like:

DESIRED STATE   CURRENT STATE           ERROR

Ready           Rejected 2 seconds ago  "network sandbox join failed:
                                        subnet sandbox join failed for
                                        "10.0.0.0/24":
                                        error creating vxlan interface:
                                        file exists"

Docker is unable to create the network sandbox required by the service.

The important part of the error is:

error creating vxlan interface: file exists

This points toward the Linux networking layer rather than the application itself.

Understanding Docker Swarm Overlay Networks

Docker Swarm uses Overlay networks to allow containers running on different nodes to communicate as if they were connected to the same virtual network.

VXLAN is used to encapsulate this traffic between Swarm nodes.

A simplified architecture looks like this:

                 Docker Swarm
                      │
               Overlay Network
                      │
                    VXLAN
                      │
              Linux network device
                      │
             Physical network
                      │
               Other Swarm nodes

The Swarm ingress network is also an Overlay network.

For example:

Network:  ingress
Subnet:   10.0.0.0/24
Gateway:  10.0.0.1
VXLAN ID: 4096

The exact subnet and VXLAN ID will depend on the cluster configuration.

Step 1: Identify the Affected Node

First determine which node is failing to start the service:

docker service ps --no-trunc <service>

For example:

ID        NAME                  NODE       DESIRED STATE   CURRENT STATE
xxxx      example_gateway.1    worker-01  Ready           Rejected

The subsequent investigation must be performed on the affected node.

This is important because the stale interface is a local Linux networking resource.

Step 2: Inspect the Docker Networks

List the Docker networks:

docker network ls

Look for the Swarm Overlay networks:

NETWORK ID     NAME       DRIVER    SCOPE
xxxxxxxxxxxx   ingress    overlay   swarm
xxxxxxxxxxxx   app_net    overlay   swarm

The ingress network is particularly important when the error mentions its subnet.

Inspect it:

docker network inspect ingress

Pay attention to:

Subnet
Gateway
VXLAN ID

For example:

{
  "Subnet": "10.0.0.0/24",
  "Gateway": "10.0.0.1",
  "com.docker.network.driver.overlay.vxlanid_list": "4096"
}

The VXLAN ID will be useful when inspecting the Linux networking interfaces.

Step 3: Inspect VXLAN Interfaces

Now inspect the VXLAN interfaces directly on the affected node:

ip -d link show type vxlan

On a healthy node, Docker manages these interfaces as part of its Overlay networking.

In the problematic case, an unexpected interface may appear:

716: vx-001000-xxxxxx: <BROADCAST,MULTICAST> mtu 1450
    state DOWN
    vxlan id 4096

The important details are:

vxlan id 4096
state DOWN

If this VXLAN ID matches the one used by the affected Docker network, the interface is a strong candidate for being stale.

Step 4: Compare the VXLAN ID

Compare the output from:

docker network inspect ingress

with:

ip -d link show type vxlan

For example:

Docker network:

Subnet:   10.0.0.0/24
VXLAN ID: 4096

and:

Linux:

vx-001000-xxxxxx
vxlan id 4096
state DOWN

This gives a useful correlation:

Docker ingress network
        │
        │ VXLAN ID 4096
        ▼
Linux VXLAN interface
vx-001000-xxxxxx
        │
        │ already exists
        ▼
Docker attempts to create it
        │
        ▼
"file exists"

Step 5: Check Docker Logs

Docker's system logs can provide additional confirmation:

sudo journalctl -u docker --since "10 minutes ago" --no-pager

For a more focused search:

sudo journalctl -u docker --since "10 minutes ago" --no-pager \
  | grep -Ei 'vxlan|sandbox|ingress|network'

The relevant error typically looks like:

Failed creating ingress network:
network sandbox join failed:
subnet sandbox join failed for "10.0.0.0/24":
error creating vxlan interface: file exists

If the same error is repeated continuously, Docker is likely retrying the network initialization while the conflicting interface remains present.

What Is Actually Happening?

The failure can be represented as follows:

Service deployment
       │
       ▼
Create network sandbox
       │
       ▼
Join Overlay network
       │
       ▼
Create VXLAN interface
       │
       ├── Interface does not exist
       │       → Create it
       │
       └── Interface already exists
               │
               ▼
           "file exists"
               │
               ▼
       Network sandbox fails
               │
               ▼
        Service is rejected

The key point is that the service fails because its network sandbox cannot be created.

The application itself may never actually start.

The Fix

Once a stale VXLAN interface has been identified with confidence, it can be removed from the affected Linux host.

For example:

sudo ip link delete vx-001000-xxxxxx

Replace the interface name with the actual interface found during the investigation.

Then restart Docker:

sudo systemctl restart docker

Docker should recreate the required networking state.

Finally, verify the service:

docker service ps --no-trunc <service>

If the problem was caused by the stale VXLAN interface, the service should now be able to start normally.

Why Not Delete the ingress Network?

A tempting solution is to remove and recreate the ingress network:

docker network rm ingress

This should not be the first troubleshooting step.

The ingress network may be perfectly healthy at the Swarm level.

If:

docker network inspect ingress

shows the expected configuration, while the affected host has a conflicting local VXLAN interface, the problem is local to that host.

Deleting the ingress network is also significantly more disruptive because it can affect multiple services across the Swarm cluster.

The preferred approach is therefore:

Check the network configuration
          │
          ▼
Check the affected node
          │
          ▼
Check VXLAN interfaces
          │
          ▼
Identify the stale interface
          │
          ▼
Remove only the stale interface
          │
          ▼
Restart Docker

A Complete Troubleshooting Checklist

When encountering:

error creating vxlan interface: file exists

follow these steps.

1. Identify the affected node

docker service ps --no-trunc <service>

2. List Overlay networks

docker network ls

3. Inspect the ingress network

docker network inspect ingress

Record:

Subnet
Gateway
VXLAN ID

4. Inspect VXLAN interfaces

Run this on the affected node:

ip -d link show type vxlan

5. Compare the VXLAN IDs

Look for an interface using the same VXLAN ID as the affected Overlay network.

For example:

Docker:
VXLAN ID: 4096

Linux:
vx-001000-xxxxxx
vxlan id 4096
state DOWN

6. Check Docker logs

sudo journalctl -u docker --since "10 minutes ago" --no-pager \
  | grep -Ei 'vxlan|sandbox|ingress|network'

7. Remove the stale interface

Only after confirming that the interface is stale:

sudo ip link delete <vxlan-interface>

8. Restart Docker

sudo systemctl restart docker

9. Verify the service

docker service ps --no-trunc <service>

Important Safety Considerations

The command:

sudo ip link delete <interface>

directly modifies the Linux networking configuration.

It should therefore only be used after identifying the interface involved in the conflict.

Do not blindly delete every VXLAN interface on a production Swarm node.

Before removing anything, verify:

• the interface is associated with the reported VXLAN ID;
• the interface appears to be stale or incorrectly left behind;
• the affected Docker network is still correctly defined;
• the operation is being performed on the node where the service is failing.

When in doubt, inspect first rather than deleting.

A Minimal Diagnostic Script

For a quick first investigation, these commands provide most of the information needed:

docker service ps --no-trunc <service>

docker network inspect ingress

ip -d link show type vxlan

sudo journalctl -u docker --since "10 minutes ago" --no-pager \
  | grep -Ei 'vxlan|sandbox|ingress|network'

If the investigation identifies a stale VXLAN interface:

sudo ip link delete <vxlan-interface>
sudo systemctl restart docker

Then:

docker service ps --no-trunc <service>

Conclusion

The Docker Swarm error:

error creating vxlan interface: file exists

does not necessarily mean that the Swarm network itself is broken.

A common cause is a stale VXLAN interface on the affected node.

The important diagnostic clues are:

network sandbox join failed

combined with:

error creating vxlan interface: file exists

The investigation should therefore move down the networking stack:

Service
  ↓
Network sandbox
  ↓
Overlay network
  ↓
VXLAN
  ↓
Linux network interface

Once the conflicting interface has been identified and confirmed as stale, removing that interface and restarting Docker can restore the node's Overlay networking without rebuilding the Swarm network.

The key lesson is simple:

When Docker Swarm reports error creating vxlan interface: file exists, inspect the VXLAN interfaces on the affected node before deleting or recreating the Swarm network.