How to Troubleshoot Container Networking Issues on macOS 15: Fix "No Network Access"

To troubleshoot container networking issues on macOS 15, verify the container-network-vmnet helper is allocating addresses in the system logs, ensure your container's networks array is populated, and restart the container system. If the default CIDR 192.168.64.1/24 conflicts with your network, override the subnet in ~/.config/container/config.toml and recreate the default network.

The apple/container project runs each container inside a lightweight Linux VM using the vmnet framework. On macOS 15, strict limitations on network isolation frequently cause "no network access" errors when the XPC helper fails to allocate a virtual interface or encounters a CIDR mismatch with the VMnet provisioned subnet.

Why Containers Lose Network Access on macOS 15

On macOS 15, the vmnet framework only supports a single default network, unlike macOS 26+ which supports multiple isolated networks. The container tool relies on the container-network-vmnet XPC helper (implemented in Sources/Plugins/NetworkVmnet/NetworkVmnetHelper.swift) to allocate virtual NICs via vmnet.framework.

The helper defaults to the CIDR 192.168.64.1/24. If this subnet conflicts with your existing network or the helper fails to start, the container receives an empty networks configuration, resulting in complete connectivity loss. According to the technical documentation in docs/technical-overview.md, this CIDR mismatch is the primary cause of networking failures on macOS 15.

The network path flows from the container CLI through the container‑apiserver, then via XPC to the container‑network‑vmnet helper, which finally attaches the interface to the lightweight VM.

Step-by-Step Diagnostics

Follow these diagnostic steps to identify the root cause of networking failures.

1. Verify Your macOS Version

Confirm you are running macOS 15, as the single-network limitation is specific to this release.

sw_vers -productVersion

2. Confirm the VMnet Helper is Running

Check that the helper is active and allocating addresses. Look for log entries containing "allocated attachment" with an address in the 192.168.64.0/24 range.

container system logs | grep container-network-vmnet

Missing entries indicate the helper failed to start or crashed.

3. List Existing Networks

On macOS 15, you should see only the default network in a running state.

container network list

The output should resemble:

NETWORK  STATE    SUBNET
default  running  192.168.64.0/24

4. Inspect Container Network State

Check if your specific container received an IP address. An empty networks array confirms the helper never allocated an interface.

container inspect <container-name> | jq '.networks'

Expected output for a healthy container:

[
  {
    "address": "192.168.64.3/24",
    "gateway": "192.168.64.1",
    "hostname": "my-container.test.",
    "network": "default"
  }
]

5. Check VMnet Framework Status (Advanced)

For low-level framework errors, query the macOS unified log for the vmnet process.

log show --predicate 'process == "container-network-vmnet"' --last 1h

Resolving Network Failures

Once diagnosed, apply these fixes ordered from least to most invasive.

6. Restart the Container System

Force the vmnet helper to re-initialize and clear stale state.

container system stop
container system start

7. Recreate the Default Network

If the network configuration is corrupted, remove the default network and restart the system. The NetworkCreate.swift implementation automatically recreates the default network on startup.

container network rm default
container system start

If the rm command fails because the network is in use, ensure all containers are stopped first.

8. Adjust the Default Subnet

If your environment already uses 192.168.64.0/24, modify the subnet in the configuration file before restarting.

cat <<EOF > ~/.config/container/config.toml
[network]
subnet = "192.168.65.1/24"
EOF
container system restart

9. Verify Connectivity

Test network access by running a container with the explicit --network default flag.

container run --rm --network default alpine ping -c 3 8.8.8.8

Source Code Architecture

Understanding the relevant source files clarifies how the network stack operates:

• Sources/Plugins/NetworkVmnet/NetworkVmnetHelper.swift: Implements the XPC helper that interfaces directly with vmnet.framework. When this helper cannot allocate an interface, the container's networks field remains empty.

• Sources/ContainerResource/Network/NetworkConfiguration.swift: Stores the plugin identifier (container-network-vmnet) that the runtime uses to select the correct network strategy, as referenced in RuntimeLinuxHelper+Start.swift.

• Sources/ContainerCommands/Network/NetworkCreate.swift: Handles the CLI command for network creation. When this command fails due to vmnet errors, the default network may enter a corrupted state.

Summary

• macOS 15 limitation: The vmnet framework supports only the single default network with a fixed CIDR of 192.168.64.1/24.
• Empty networks array: Indicates the container-network-vmnet helper failed to allocate an IP, usually due to a CIDR conflict or helper startup failure.
• Log locations: Check container system logs for helper allocation messages and log show for framework-level errors.
• Resolution path: Restart the system, delete and recreate the default network, or override the subnet in ~/.config/container/config.toml to avoid CIDR clashes.

Frequently Asked Questions

Why does my container have an empty networks array?

An empty networks array indicates the container-network-vmnet helper could not allocate a virtual interface from vmnet.framework. This typically occurs on macOS 15 when the default CIDR 192.168.64.1/24 conflicts with an existing network on your host, or when the XPC helper failed to start. Inspect the system logs for allocation failures.

Can I create multiple isolated networks on macOS 15?

No. According to the technical overview in the apple/container repository, macOS 15 only supports the single default network via the vmnet framework. Multiple isolated networks require macOS 26 or later.

Where is the network subnet configuration stored?

User-specific network settings are stored in ~/.config/container/config.toml. The plugin identifier that determines which network strategy to use (vmnet vs. other backends) is defined in Sources/ContainerResource/Network/NetworkConfiguration.swift.

How do I know if the vmnet helper is failing?

Run container system logs | grep container-network-vmnet. If you see no "allocated attachment" messages or encounter errors when running container network list, the helper is not functioning. Check the macOS unified logs with log show --predicate 'process == "container-network-vmnet"' for low-level framework errors indicating why the NIC creation failed.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}