How to fix Error response from daemon: failed to create the macvlan port: device or resource busy in Docker

DockerADVANCEDMEDIUMUpdated Dec 6, 2025· 390 views

This error occurs when Docker cannot create a macvlan network interface because the parent network interface is already in use or misconfigured. Common fixes include switching to ipvlan, using a different parent interface, or removing stale network configurations.

Quick fix

Fixes Error response from daemon: failed to create the macvlan port: device or resource busy

# Remove existing macvlan network
docker network rm my_macvlan_network

# Create ipvlan network instead
docker network create -d ipvlan \
  --subnet=192.168.1.0/24 \
  --gateway=192.168.1.1 \
  -o parent=eth0 \
  my_ipvlan_network
  1. Switch from macvlan to ipvlan
  2. Check for existing macvlan networks and interfaces
  3. Remove conflicting Docker networks
  4. Use a physical interface instead of a bridge
docker — error
# Remove existing macvlan network
docker network rm my_macvlan_network
# Create ipvlan network instead
docker network create -d ipvlan \
  --subnet=192.168.1.0/24 \
  --gateway=192.168.1.1 \
  -o parent=eth0 \
  my_ipvlan_network
Error response from daemon: failed to create the macvlan port: device or resource busy

What this error means

The "failed to create the macvlan port: device or resource busy" error indicates that Docker's attempt to create a virtual network interface using the macvlan driver has failed. The macvlan driver creates virtual network interfaces that appear as physically separate devices on your network, each with their own MAC address. This error typically occurs because: - The parent network interface (e.g., eth0) is already being used by another macvlan network - A previous container or network wasn't properly cleaned up, leaving stale macvlan interfaces - The parent interface is a bridge interface (like br0) which is unreliable with macvlan - There's a MAC address conflict with an existing container or network interface - On NAS systems (Synology, QNAP), the interface naming differs from standard Linux Docker's macvlan driver requires exclusive access to create sub-interfaces on the parent. When the kernel reports "device or resource busy," it means something is blocking this operation at the network stack level. This is often a long-standing kernel limitation rather than a Docker-specific bug.

Typical symptoms

  • Container fails to start with 'failed to create the macvlan port: device or resource busy'
  • docker network create with macvlan driver fails immediately
  • docker-compose up fails when using macvlan network configuration
  • Error appears after system reboot or Docker restart
  • Works on one interface but fails on another
  • Error occurs intermittently without configuration changes
  • NAS Docker applications (Pi-hole, etc.) fail to start with this error

Common causes

  1. Another macvlan network is already using the same parent interface
  2. Stale macvlan interfaces from previous containers weren't cleaned up
  3. The parent interface is a bridge (br0) rather than a physical interface (eth0)
  4. MAC address collision with an existing container or interface
  5. On Synology/QNAP NAS, using wrong interface name (eth0 vs ovs_eth0)
  6. Kernel macvlan module is not loaded or not supported
  7. Wireless interface being used as parent (macvlan doesn't support WiFi)
  8. Docker daemon has cached stale network state

How to fix "Error response from daemon: failed to create the macvlan port: device or resource busy"

1Switch from macvlan to ipvlan

The most reliable fix is to use ipvlan instead of macvlan. Ipvlan shares the parent's MAC address and avoids many macvlan-specific issues:

bash
# Remove existing macvlan network
docker network rm my_macvlan_network

# Create ipvlan network instead
docker network create -d ipvlan \
  --subnet=192.168.1.0/24 \
  --gateway=192.168.1.1 \
  -o parent=eth0 \
  my_ipvlan_network

For docker-compose, update your configuration:

yaml
networks:
  my_network:
    driver: ipvlan
    driver_opts:
      parent: eth0
    ipam:
      config:
        - subnet: 192.168.1.0/24
          gateway: 192.168.1.1

Note: Ipvlan L2 mode behaves similarly to macvlan but without the MAC address complications.

2Check for existing macvlan networks and interfaces

Identify if there are existing macvlan networks using the same parent:

bash
# List all Docker networks
docker network ls

# Inspect macvlan networks to see their parent interface
docker network inspect $(docker network ls --filter driver=macvlan -q) 2>/dev/null

# Check for stale macvlan interfaces on the host
ip link show type macvlan

# Check all network interfaces
ip addr show

If you find stale interfaces (like dm-*, mv-*, or macvlan*), remove them:

bash
sudo ip link delete <interface_name>
3Remove conflicting Docker networks

Clean up Docker networks that may be holding the interface:

bash
# Stop all containers using the network
docker stop $(docker ps -q)

# Remove the problematic network
docker network rm <network_name>

# Remove all unused networks
docker network prune -f

# For a complete cleanup, also prune other resources
docker system prune -af

After cleanup, try recreating your macvlan network.

4Use a physical interface instead of a bridge

Macvlan works best with physical interfaces, not bridges. Check your current setup:

bash
# List all interfaces and their types
ip -d link show

# Look for bridge interfaces (br0, docker0, etc.)
bridge link show 2>/dev/null || ip link show type bridge

If your parent is a bridge (like br0), use the underlying physical interface instead:

bash
# Instead of parent=br0, use:
docker network create -d macvlan \
  --subnet=192.168.1.0/24 \
  --gateway=192.168.1.1 \
  -o parent=eth0 \
  my_macvlan

On a bonded interface, use the bond directly:

bash
-o parent=bond0
5Fix interface name on Synology/NAS systems

Synology and some other NAS systems use Open vSwitch, which requires different interface names:

bash
# Check available interfaces on Synology
ip addr show

# Look for ovs_eth0 instead of eth0

Update your Docker network to use the correct interface:

bash
# For Synology DSM
docker network create -d macvlan \
  --subnet=192.168.1.0/24 \
  --gateway=192.168.1.1 \
  -o parent=ovs_eth0 \
  my_macvlan

For QNAP or other NAS systems, check the interface names with ip addr and use the appropriate one.

6Restart Docker daemon

Sometimes Docker's network state becomes stale. A daemon restart can clear this:

bash
# Stop all containers first
docker stop $(docker ps -q)

# Restart Docker daemon
sudo systemctl restart docker

# On systems without systemd
sudo service docker restart

# On Synology
sudo synoservice --restart pkgctl-Docker

After restart, try creating your network again.

7Try a different MAC address

If there's a MAC address conflict, explicitly set a unique MAC:

bash
docker run --network my_macvlan \
  --mac-address 02:42:ac:11:00:02 \
  your_image

Or in docker-compose:

yaml
services:
  myservice:
    image: your_image
    mac_address: "02:42:ac:11:00:02"
    networks:
      - my_macvlan

Note: Use locally administered MAC addresses (second hex digit should be 2, 6, A, or E).

8Reboot the host system

If all else fails, a full system reboot clears all network state:

bash
sudo reboot

This resolves issues caused by:
- Kernel-level stuck resources
- Stale network namespace references
- Improperly released interfaces

After reboot, try creating your macvlan network before starting any other Docker containers.

Advanced notes

Kernel requirements: Macvlan requires Linux kernel 3.9+ (4.0+ recommended). Check your kernel version:

bash
uname -r

Verify macvlan module is available:

bash
modprobe macvlan
lsmod | grep macvlan

Platform limitations:
- Macvlan only works on Linux hosts, not Docker Desktop for Mac/Windows
- Most cloud providers (AWS, Azure, GCP) block macvlan networking
- Macvlan is not supported in Docker rootless mode
- WiFi interfaces cannot be used as parent interfaces (IEEE 802.11 limitation)

Promiscuous mode: Your network equipment must support promiscuous mode for macvlan to work. This allows one physical interface to have multiple MAC addresses:

bash
# Enable promiscuous mode on the interface
sudo ip link set eth0 promisc on

Macvlan modes: Docker supports different macvlan modes:
- bridge (default): Containers can communicate with each other
- private: Containers isolated from each other
- vepa: Traffic goes through external switch for inter-container communication
- passthru: Single container gets exclusive access to the interface

bash
docker network create -d macvlan \
  -o macvlan_mode=bridge \
  -o parent=eth0 \
  --subnet=192.168.1.0/24 \
  my_macvlan

Host-to-container communication: By design, the host cannot directly communicate with macvlan containers. To enable this, create a macvlan interface on the host:

bash
# Create a macvlan interface on the host
sudo ip link add macvlan0 link eth0 type macvlan mode bridge
sudo ip addr add 192.168.1.250/24 dev macvlan0
sudo ip link set macvlan0 up

# Now the host can reach containers at 192.168.1.x

Docker Compose with ipvlan L3 mode: For advanced isolation, use ipvlan L3:

yaml
networks:
  isolated:
    driver: ipvlan
    driver_opts:
      parent: eth0
      ipvlan_mode: l3
    ipam:
      config:
        - subnet: 10.0.0.0/24

Note: L3 mode requires static routes on your gateway router.

dhcpcd conflicts (Raspberry Pi): On Raspberry Pi, dhcpcd may interfere with Docker networks. Add to /etc/dhcpcd.conf:

bash
denyinterfaces veth* mv* dm*

Long-standing kernel issue: The "device or resource busy" error is related to kernel-level network namespace handling. This has been reported across multiple kernel versions and isn't always fixable from userspace. If you consistently hit this issue, ipvlan is the recommended alternative.

Frequently asked questions

What does "Error response from daemon: failed to create the macvlan port: device" mean?
The "failed to create the macvlan port: device or resource busy" error indicates that Docker's attempt to create a virtual network interface using the macvlan driver has failed. The macvlan driver creates virtual network interfaces that appear as physically separate devices on your network, each with their own MAC address. , eth0) is already being used by another macvlan network - A previous container or network wasn't properly cleaned up, leaving stale macvlan interfaces - The parent interface is a bridge interface (like br0) which is unreliable with macvlan - There's a MAC address conflict with an existing container or network interface - On NAS systems (Synology, QNAP), the interface naming differs from standard Linux Docker's macvlan driver requires exclusive access to create sub-interfaces on the parent.
How do I fix "Error response from daemon: failed to create the macvlan port: device"?
This error occurs when Docker cannot create a macvlan network interface because the parent network interface is already in use or misconfigured. Common fixes include switching to ipvlan, using a different parent interface, or removing stale network configurations.
What causes "Error response from daemon: failed to create the macvlan port: device"?
Another macvlan network is already using the same parent interface Stale macvlan interfaces from previous containers weren't cleaned up The parent interface is a bridge (br0) rather than a physical interface (eth0)
Is the "Error response from daemon: failed to create the macvlan port: device" error serious?
It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading