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.
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.
The most reliable fix is to use ipvlan instead of macvlan. Ipvlan shares the parent's MAC address and avoids many macvlan-specific issues:
# 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_networkFor docker-compose, update your configuration:
networks:
my_network:
driver: ipvlan
driver_opts:
parent: eth0
ipam:
config:
- subnet: 192.168.1.0/24
gateway: 192.168.1.1Note: Ipvlan L2 mode behaves similarly to macvlan but without the MAC address complications.
Identify if there are existing macvlan networks using the same parent:
# 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 showIf you find stale interfaces (like dm-*, mv-*, or macvlan*), remove them:
sudo ip link delete <interface_name>Clean up Docker networks that may be holding the interface:
# 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 -afAfter cleanup, try recreating your macvlan network.
Macvlan works best with physical interfaces, not bridges. Check your current setup:
# 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 bridgeIf your parent is a bridge (like br0), use the underlying physical interface instead:
# 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_macvlanOn a bonded interface, use the bond directly:
-o parent=bond0Synology and some other NAS systems use Open vSwitch, which requires different interface names:
# Check available interfaces on Synology
ip addr show
# Look for ovs_eth0 instead of eth0Update your Docker network to use the correct interface:
# For Synology DSM
docker network create -d macvlan \
--subnet=192.168.1.0/24 \
--gateway=192.168.1.1 \
-o parent=ovs_eth0 \
my_macvlanFor QNAP or other NAS systems, check the interface names with ip addr and use the appropriate one.
Sometimes Docker's network state becomes stale. A daemon restart can clear this:
# 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-DockerAfter restart, try creating your network again.
If there's a MAC address conflict, explicitly set a unique MAC:
docker run --network my_macvlan \
--mac-address 02:42:ac:11:00:02 \
your_imageOr in docker-compose:
services:
myservice:
image: your_image
mac_address: "02:42:ac:11:00:02"
networks:
- my_macvlanNote: Use locally administered MAC addresses (second hex digit should be 2, 6, A, or E).
If all else fails, a full system reboot clears all network state:
sudo rebootThis 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.
Kernel requirements: Macvlan requires Linux kernel 3.9+ (4.0+ recommended). Check your kernel version:
uname -rVerify macvlan module is available:
modprobe macvlan
lsmod | grep macvlanPlatform 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:
# Enable promiscuous mode on the interface
sudo ip link set eth0 promisc onMacvlan 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
docker network create -d macvlan \
-o macvlan_mode=bridge \
-o parent=eth0 \
--subnet=192.168.1.0/24 \
my_macvlanHost-to-container communication: By design, the host cannot directly communicate with macvlan containers. To enable this, create a macvlan interface on the host:
# 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.xDocker Compose with ipvlan L3 mode: For advanced isolation, use ipvlan L3:
networks:
isolated:
driver: ipvlan
driver_opts:
parent: eth0
ipvlan_mode: l3
ipam:
config:
- subnet: 10.0.0.0/24Note: 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:
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.
image operating system "linux" cannot be used on this platform
How to fix 'image operating system linux cannot be used on this platform' in Docker
manifest unknown: manifest unknown
How to fix 'manifest unknown' in Docker
cannot open '/etc/passwd': Permission denied
How to fix 'cannot open: Permission denied' in Docker
Error response from daemon: failed to create the ipvlan port
How to fix 'failed to create the ipvlan port' in Docker
toomanyrequests: Rate exceeded for anonymous users
How to fix 'Rate exceeded for anonymous users' in Docker Hub