apple / apple/container

[Bug]: `container machine create` succeeds for images without /sbin/init, then boot fails with a misleading error

Open
#2,024 2 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. Create a machine from any standard application image (no init system):

```console
$ container machine create ubuntu:latest --name repro-machine
[0/3] [0s]
[1/3] Fetching image [0s]
[2/3] Unpacking image [0s]
Error: failed to create process in container (cause: "internalError: "failed to create process ffe595ed-... in container repro-machine-a60d5f (cause: "invalidState: "cannot exec: container is not running"")"")
```

2. The machine is nevertheless created, and is permanently unbootable:

```console
$ container machine ls
NAME CREATED IP CPUS MEMORY DISK STATE DEFAULT
repro-machine 2026-07-27 00:12:01 - 7 4G 197M stopped
```

3. The actual cause only appears in `container machine logs repro-machine`:

```
/sbin.machine/init: 74: exec: /sbin/init: not found
```

The same happens with `alpine:3.22` — which is the example image shown in `container machine --help` and in `MachineCreate.swift`:

```
EXAMPLES:
List available images and create a container machine:
$ container machine create alpine:3.22 --name my-machine
```

Alpine ships neither `/sbin/init` nor `getent`, so the tool's own help example produces a machine that cannot boot.

## Problem description

The machine boot flow bind-mounts a helper script that ends with `exec /sbin/init` (`Sources/Plugins/MachineAPIServer/Resources/init:74`). When the image has no init system — true of essentially every standard application image on Docker Hub, including `ubuntu:latest` and `alpine` — the initial process dies immediately. `MachinesService.create` (`Sources/Services/MachineAPIService/Server/MachinesService.swift:178-227`) performs no validation of the image, so:

1. **The failure surfaces at the wrong step with the wrong message.** The user sees `cannot exec: container is not running` from the *user-setup exec* that runs after boot, not the underlying `exec: /sbin/init: not found`. Nothing points at the image being unsuitable. Judging by #1669, #1685, and #1689, several users have independently hit this and needed community help to learn that machine images must ship an init system.

2. **The broken machine is still created** and shows up in `container machine ls` in `stopped` state, indistinguishable from a healthy stopped machine. Every subsequent `container machine run` fails the same way.

3. **The CLI help recommends an image that cannot work.** `alpine:3.22` in the `container machine` examples fails the documented requirement in `docs/container-machine.md` ("Any Linux image that includes `/sbin/init` works").

### Expected behavior

- `container machine create` validates the unpacked rootfs and fails fast with an actionable error when `/sbin/init` is missing, e.g.:

```
Error: image "docker.io/library/ubuntu:latest" cannot be used as a container machine:
it does not contain /sbin/init. Machine images must include an init system (for
example systemd). See docs/container-machine.md ("Bring your own container machine
image") for a working Dockerfile.
```

The check is cheap — the rootfs is already unpacked/cloned at create time, and `MachineBundle` knows the filesystem. (If create-time validation is undesirable for some reason, at minimum the boot error should propagate the real cause from the guest log instead of `cannot exec: container is not running`.)

- No machine record is left behind when creation fails validation (or the partial bundle is cleaned up).

- The help examples in `MachineCreate.swift` / `container machine --help` use an image that actually boots, or explicitly point at the "Bring your own container machine image" doc section.

Happy to send a PR for the validation check and the help-text fix if the approach sounds right to the maintainers.

Related: #1669, #1685, #1689 (users hitting this symptom), #1700 (docs framing of machines vs containers).

## Environment

- OS: macOS 26.5 (25F71)
- Xcode: n/a (installed from release pkg)
- Container: container CLI version 1.1.0 (build: release, commit: 5973b9c)

Contributor guide

Open the contributing guide

Research direction

Read MachinesService.create in Sources/Services/MachineAPIService/Server/MachinesService.swift and the helper at Sources/Plugins/MachineAPIServer/Resources/init to understand the current create and boot flow. Check the example in MachineCreate.swift and the requirement in docs/container-machine.md. Done means unsuitable images fail with an actionable /sbin/init error, no broken machine remains, and the help example uses a bootable image.

Written by the indexing model from the issue text.

Assessment

Tech stack
swift
Domain
cli, operating-systems
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
68/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.