Skip to content

Restore macOS 15 networking troubleshooting steps #1646

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
bte808 wants to merge 2 commits into
base: main
Choose a base branch
from
+13 −1
Open

Restore macOS 15 networking troubleshooting steps #1646

Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
4c547bd
Restore macOS 15 networking troubleshooting steps
bte808 Jun 4, 2026
b2e0a97
Use system config for macOS 15 networking docs
bte808 Jun 4, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 12 additions & 1 deletion docs/technical-overview.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -74,4 +74,15 @@ In macOS 15, all containers attach to the default vmnet network. The `container

In macOS 15, limitations in the vmnet framework mean that the container network can only be created when the first container starts. Since the network XPC helper provides IP addresses to containers, and the helper has to start before the first container, it is possible for the network helper and vmnet to disagree on the subnet address, resulting in containers that are completely cut off from the network.

Normally, vmnet creates the container network using the CIDR address 192.168.64.1/24, and on macOS 15, `container` defaults to using this CIDR address in the network helper. If your containers have no network access on macOS 15, see [All networking fails on macOS 15](troubleshooting.md#all-networking-fails-on-macos-15) for diagnosis and remediation steps.
Normally, vmnet creates the container network using the CIDR address 192.168.64.1/24, and on macOS 15, `container` defaults to using this CIDR address in the network helper. To diagnose and resolve issues stemming from a subnet address mismatch between vmnet and the network helper:

- Before creating the first container, scan the output of the command `ifconfig` for a bridge interface named similarly to `bridge100`.
- After creating the first container, run `ifconfig` again, and locate the new bridge interface to determine the container subnet address.
- Run `container ls` to check the IP address given to the container by the network helper. If the address corresponds to a different network:
- Run `container system stop` to terminate the services for `container`.
- Using the macOS `defaults` command, update the default subnet value used by the network helper process. For example, if the bridge address shown by `ifconfig` is 192.168.66.1, run:
```bash
defaults write com.apple.container.defaults network.subnet 192.168.66.1/24

@katiewasnothere katiewasnothere Jun 4, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This part of the steps is not longer accurate since we moved away from defaults. See https://github.com/apple/container/blob/main/docs/tutorials/container-system-config-tutorial.md instead.

```
- Run `container system start` to launch services again.
- Try running the container again and verify that its IP address matches the current bridge interface value.