# How to Debug Container Networking Issues on Different macOS Versions

> Troubleshoot container networking on macOS. Learn to diagnose XPC helper status, inspect network settings, and check logs for common issues across macOS versions.

- Repository: [Apple/container](https://github.com/apple/container)
- Tags: how-to-guide
- Published: 2026-07-04

---

**To debug container networking issues on macOS, verify the `container-network-vmnet` XPC helper is active via `launchctl`, inspect network configuration with `container network inspect`, and check system logs for subnet mismatches or allocation failures, noting that macOS 15 restricts containers to a single default network while macOS 26+ supports multiple user-defined networks.**

The `apple/container` repository implements a container runtime that executes workloads inside lightweight Linux VMs, relying on the **vmnet** framework for virtual network provisioning. Because the `container-network-vmnet` helper process and vmnet framework behavior vary between macOS releases, debugging container networking requires version-specific diagnostic approaches and an understanding of the underlying XPC architecture described in [`docs/technical-overview.md`](https://github.com/apple/container/blob/main/docs/technical-overview.md) (lines 36-44).

## Understanding the Container Network Architecture

The networking stack relies on cooperation between userspace daemons and the macOS kernel. According to [`docs/technical-overview.md`](https://github.com/apple/container/blob/main/docs/technical-overview.md), the **`container-apiserver`** initiates an XPC helper called **`container-network-vmnet`**, which creates the virtual network interface and allocates IP addresses to containers (lines 36-44). The XPC plumbing that launches this helper is implemented in [`Sources/ContainerPlugin/PluginStateRoot.swift`](https://github.com/apple/container/blob/main/Sources/ContainerPlugin/PluginStateRoot.swift), while container runtime startup logic resides in [`Sources/ContainerBuild/BuildPipelineHandler.swift`](https://github.com/apple/container/blob/main/Sources/ContainerBuild/BuildPipelineHandler.swift). Each container runs inside its own Linux VM, with macOS supplying the underlying virtual network through the vmnet framework; when this helper fails or returns an unexpected subnet, containers may start without IP addresses or with isolated networking.

## macOS Version-Specific Network Capabilities

The vmnet framework implementation differs significantly between macOS 15 and macOS 26+, directly impacting available CLI commands and failure modes.

### macOS 26+ and Later

On macOS 26+, the framework provides **full vmnet support**, allowing multiple user-defined networks per host. You can create isolated network segments using commands like `container network create`, `list`, `inspect`, and `delete` as documented in [`docs/command-reference.md`](https://github.com/apple/container/blob/main/docs/command-reference.md) (lines 768-850). Typical failures on this version stem from configuration errors such as duplicate subnets or MAC-address conflicts rather than framework limitations.

### macOS 15

macOS 15 imposes strict limitations: vmnet can provide only a **single default network**, and containers remain isolated from each other by design. The `container network` commands are unavailable, and the **`--network` flag is explicitly rejected** by the CLI according to [`docs/technical-overview.md`](https://github.com/apple/container/blob/main/docs/technical-overview.md) (lines 65-72). The most common failure mode occurs when the network helper and vmnet disagree on the subnet, causing all containers to start without IP addresses (lines 73-77).

## Debugging Container Networking on macOS 26+

Follow these steps to diagnose connectivity issues on systems running macOS 26 or later:

1. **Verify the runtime helper is running**  
   Confirm that the `container-runtime-linux` XPC helper is active:
   ```bash
   launchctl list | grep container-runtime-linux
   ```

2. **Inspect the network configuration**  
   Use `container network inspect` to view subnet, gateway, and container IP assignments in JSON format as shown in [`docs/command-reference.md`](https://github.com/apple/container/blob/main/docs/command-reference.md) (lines 842-853):
   ```bash
   container network inspect default | jq .
   ```

3. **Check the container's assigned IP**  
   Execute `ip addr` inside the container to verify the interface configuration matches the expected subnet (default is `192.168.64.1/24`):
   ```bash
   container exec <id>` ip -4 addr show eth0
   ```

4. **Validate vmnet subnet alignment**  
   If the container IP falls outside the `192.168.64.0/24` range, the network helper likely failed to initialize correctly or the vmnet framework allocated an unexpected CIDR.

5. **Review network helper logs**  
   Query the system log for specific allocation errors from the `container-network-vmnet` process:
   ```bash
   log show --predicate 'process == "container-network-vmnet"' --info --last 1h
   ```

## Debugging Container Networking on macOS 15

On macOS 15, network debugging focuses on the single default network and lazy initialization behavior:

1. **Confirm default network usage**  
   Only the `default` network exists on this version:
   ```bash
   container network list
   ```

2. **Ensure the first container has started**  
   The network is created lazily when the first container runs. If you stop all containers, the network tears down, potentially leaving subsequent containers without connectivity until a new container initializes the interface.

3. **Check for subnet mismatch errors**  
   If every container reports "no network," examine the helper logs for allocation failures:
   ```bash
   log show --predicate 'process == "container-network-vmnet"' --info --last 1h
   ```

4. **Recreate the network if necessary**  
   Force the helper to recreate the default network by running a test container:
   ```bash
   container network delete default   # May be a no-op on macOS 15

   container run --rm alpine ping -c 1 8.8.8.8
   ```

   If the helper reports a different CIDR than expected, reboot the host or reinstall the `container` CLI to reset the vmnet state.

## Universal Troubleshooting Techniques

These diagnostic methods apply across all supported macOS versions:

- **Run `container system status`** to confirm that `container-apiserver`, `container-network-vmnet`, and the runtime helper are all active simultaneously.

- **Verify the XPC socket** at `/var/run/container/network` (or equivalent socket location) exists, indicating the network helper is ready to accept connections.

- **Monitor network I/O counters** using `container stats`. If `networkRxBytes` and `networkTxBytes` remain zero, the container cannot reach the vmnet bridge as noted in [`docs/how-to.md`](https://github.com/apple/container/blob/main/docs/how-to.md) (lines 449-456).

- **Upgrade to macOS 26+** when possible, as many vmnet limitations and single-network constraints are removed in later releases.

## Summary

- The `container-network-vmnet` XPC helper is responsible for IP allocation and requires active `container-runtime-linux` support.
- macOS 26+ supports multiple user-defined networks via `container network create`, while macOS 15 is restricted to a single default network with no `--network` flag support.
- Debug by checking `launchctl` for helper status, using `container network inspect` for configuration details, and querying logs with `log show --predicate 'process == "container-network-vmnet"'`.
- On macOS 15, network creation is lazy; ensure at least one container is running to maintain the vmnet interface.
- Consult [`Sources/ContainerPlugin/PluginStateRoot.swift`](https://github.com/apple/container/blob/main/Sources/ContainerPlugin/PluginStateRoot.swift) for XPC startup issues and [`docs/technical-overview.md`](https://github.com/apple/container/blob/main/docs/technical-overview.md) for architectural constraints.

## Frequently Asked Questions

### Why does my container have no IP address on macOS 15?

The most common cause is a subnet mismatch between the `container-network-vmnet` helper and the vmnet framework. On macOS 15, if the helper fails to allocate an address from the expected `192.168.64.0/24` range, containers start without network interfaces. Check the system logs for "allocated attachment ... failed" messages and reboot the host if the CIDR has drifted from the expected default.

### Can I create custom networks on macOS 15?

No. According to [`docs/technical-overview.md`](https://github.com/apple/container/blob/main/docs/technical-overview.md) (lines 65-72), macOS 15 only supports a single default network, and the `container network create` command is unavailable. You must upgrade to macOS 26+ to define multiple isolated networks or specify custom subnets.

### How do I verify the network helper is actually running?

Execute `launchctl list | grep container-runtime-linux` to confirm the XPC helper process is loaded. Additionally, run `container system status` to verify that `container-apiserver` has successfully established communication with `container-network-vmnet`. If the helper is missing, containers will fail to acquire IP addresses entirely.

### What log predicate should I use to find vmnet errors?

Use the predicate `process == "container-network-vmnet"` with the `log show` command. For example: `log show --predicate 'process == "container-network-vmnet"' --info --last 30m`. This filters the unified log to show only allocation attempts, subnet creation messages, and attachment failures from the network helper.