apple / apple/container

Bug]: VirtualizationFramework fails to start any containers on macOS 26.3 (ARM64)

Open
#1,254 5 comments 0 reactions 0 assignees View on GitHub
Dominant language
Swift
Stars
49.9k
Forks
1.8k
Avg merge
1d 20h
Merged PRs (30d)
22

Description

### I have done the following

- [x] I have searched the existing issues
- [x] If possible, I've reproduced the issue using the 'main' branch of this project

### Steps to reproduce

1. Install Apple Container 0.9.0 on macOS 26.3 (25D125, ARM64 M4 Mac Mini)
2. Install Kata kernel:

bash
curl -L https://github.com/kata-containers/kata-containers/releases/download/3.26.0/kata-static-3.26.0-arm64.tar.zst -o /tmp/kata-kernel.tar.zst
container system kernel set --tar /tmp/kata-kernel.tar.zst --binary ./opt/kata/share/kata-containers/vmlinuz.container --force

3. Enable IP forwarding and NAT (per qwibitai/nanoclaw#178):

bash
sudo sysctl -w net.inet.ip.forwarding=1
echo "nat on en1 from 192.168.64.0/24 to any -> (en1)" | sudo pfctl -ef -

4. Start container system: `container system start`
5. Try any build: `container build -t test -f Dockerfile .`
6. Or even simple run: `container run --rm alpine:latest echo test`

### Current behavior

**Every container operation fails** with VirtualizationFramework error:

Error: internalError: "failed to bootstrap container" (cause: "internalError: "failed to bootstrap container buildkit (cause: "unknown: "Error Domain=VZErrorDomain Code=1 "The virtual machine failed to start." UserInfo={NSLocalizedFailure=Internal Virtualization error., NSLocalizedFailureReason=The virtual machine failed to start.}"")"")
This affects:
- `container build` (buildkit container won't start)
- `container run` (any container image)
- Even minimal Alpine images fail

### Expected behavior

Containers should start successfully. The buildkit VM and any runtime containers should bootstrap using the Virtualization.framework.

### Additional context

This appears to be a **macOS Virtualization.framework bug** affecting macOS Sequoia 26.x on ARM64.
**Identical issue reported elsewhere:**
- [containers/podman#28017](https://github.com/containers/podman/issues/28017) - Podman + vfkit hitting same VZErrorDomain Code=1 on macOS 26.2 ARM64
- Quote from that issue: "vfkit crashes with trace trap when attempting to start the VM via the macOS Virtualization.framework"

**What I've verified:**
- ✅ Kernel installed correctly (`vmlinuz.container` from Kata 3.26.0)
- ✅ Rosetta 2 installed
- ✅ IP forwarding enabled (`net.inet.ip.forwarding: 1`)
- ✅ NAT rules configured (`pfctl -s nat` shows rules)
- ✅ API server running
- ❌ Any VM fails to start (even minimal configs)

**Impact:** This blocks **all Apple Container usage** on macOS 26.3 ARM64. No workaround found.

**Related issues:**
- #1250 - Similar errors in CI (TestCLIBuildBase)
- #857 - XPC timeout (different but buildkit-related)
- #931 - VM hangs/crashes (performance, not bootstrap failure)

This needs OS-level fixes from Apple or workaround guidance from the Apple Container team.

### Environment

```markdown
- **OS**: macOS 26.3 (25D125)
- **Architecture**: ARM64 (M4 Mac Mini)
- **Xcode**: Not installed
- **Container**: container CLI version 0.9.0 (build: release, commit: 3e49dce)
- **Rosetta**: Installed (`softwareupdate --install-rosetta` succeeded)
- **SIP**: Enabled (`csrutil status` shows System Integrity Protection status: enabled)
```

### Relevant log output

```shell
$ container system status
apiserver is running
application data root: /Users/pinch/Library/Application Support/com.apple.container/
application install root: /usr/local/
container-apiserver version: container-apiserver version 0.9.0 (build: release, commit: 3e49dce)
container-apiserver commit: 3e49dcef4e48121fb26a7e41f8730d7a81f5c3be

$ container build -t test -f Dockerfile .
Error: internalError: "failed to bootstrap container" (cause: "internalError: "failed to bootstrap container buildkit (cause: "unknown: "Error Domain=VZErrorDomain Code=1 "The virtual machine failed to start." UserInfo={NSLocalizedFailure=Internal Virtualization error., NSLocalizedFailureReason=The virtual machine failed to start.}"")"")

$ container run --rm alpine:latest echo test
Error: internalError: "failed to bootstrap container" (cause: "internalError: "failed to bootstrap container 80971e12-1dd1-4f4d-9bf0-34308484c490 (cause: "unknown: "Error Domain=VZErrorDomain Code=1 "The virtual machine failed to start." UserInfo={NSLocalizedFailure=Internal Virtualization error., NSLocalizedFailureReason=The virtual machine failed to start.}"")"")
```

### Code of Conduct

- [x] I agree to follow this project's Code of Conduct

Contributor guide

Open the contributing guide

Research direction

Start by reproducing the failure with `container system start`, `container build`, and `container run` on macOS 26.3 ARM64, then compare the behavior with related issues #1250 and #931 and the linked Podman report. Done means identifying a project-level workaround or confirming the required Apple Virtualization.framework fix so buildkit and runtime containers start successfully.

Written by the indexing model from the issue text.

Assessment

Tech stack
macos, swift
Domain
operating-systems
Issue type
Bug
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.