How to Troubleshoot Container Startup Failures and View Boot Logs in Apple Container

Use container logs --boot <name> to stream the vminitd.log file from the container's bundle and identify exactly where the VM boot sequence failed.

When a container fails to start in the apple/container framework, the failure typically occurs during the lightweight VM initialization before user code ever executes. The runtime captures all kernel and init-process output to a persistent boot log, making it the primary diagnostic source for resolving startup failures.

Where Boot Logs Are Stored

The apple/container runtime wires boot-log handling directly into the runtime service. In Sources/Services/RuntimeLinux/Server/RuntimeService.swift (lines 73–74), the service configures a BootLog instance that writes to a specific path inside the container’s bundle. The concrete file location is defined in Sources/Services/MachineAPIService/Client/MachineBundle.swift (lines 28–52), which defaults to vminitd.log within the bundle directory. When the VM boots, the vminitd init daemon streams its messages to this file in real time.

Viewing Boot Logs

Retrieve the Complete Boot Log

To view the static contents of the boot log for a running or failed container, use the --boot flag with the container logs command:

container logs --boot my-web-server

This command opens the vminitd.log file from the container’s bundle and outputs its contents to the terminal.

Follow Logs in Real Time

Because the boot log is written during the VM initialization sequence, you can follow it live as the container starts using the -f or --follow flag:

container logs --boot -f my-web-server

Run this command in one terminal while executing container run or container start in another to watch the boot sequence progress.

View Standard Application Logs

Once the VM successfully boots, the init daemon redirects output to the container’s standard streams. To view only the post-boot stdout and stderr, omit the --boot flag:

container logs my-web-server

Troubleshooting Startup Failures

1. Check Container State

First, verify whether the container reached a running state or halted during boot. Use container ps or container list to inspect the status:

container ps

A status of stopped immediately after a create or run command strongly indicates a VM boot failure rather than an application-level error.

2. Inspect the Boot Log for Errors

Open the boot log and scan for specific failure points. Look for these patterns:

• Kernel messages – Lines prefixed with [ 0.xxx] indicate hardware detection, driver loading, and filesystem mounting.
• Init daemon messages – Entries starting with info vminitd : confirm the boot sequence steps.
• Fatal errors – Strings like "failed to mount rootfs", "cannot find /etc/hosts", or custom init-script failures indicate the specific subsystem that failed.

Filter for specific init scripts or error patterns using standard Unix tools:

container logs --boot my-web-server | grep "custom-init"

3. Verify Boot Configuration

The VM boot configuration is stored in boot-config.json inside the bundle directory, adjacent to the boot log. Misconfigured network settings, invalid kernel paths, or incorrect --init-image references surface here. Inspect the active configuration using:

container inspect my-web-server --format json | jq .bootConfig

Alternatively, access the file directly if you know the bundle path:

cat $(container info --bundle-path)/boot-config.json

4. Enable Debug Logging

For deeper visibility into the runtime’s behavior, enable verbose logging. Pass the --debug flag to the container logs command or set the environment variable CONTAINER_DEBUG=1 to capture detailed XPC messages between the CLI and the runtime service:

container run --debug --name my-web-server registry.example.com/image:latest

5. Validate Host Prerequisites

Some failures originate from missing host capabilities rather than container configuration. The boot log may indicate that virtualization features are unavailable. Ensure the host is an Apple M3 or newer with a kernel that explicitly exposes virtualization capabilities. The runtime requires these features to initialize the lightweight VM.

Practical Examples

Re-run a container with explicit debugging and follow the boot log:

# Terminal 1: Follow the boot log

container logs --boot -f my-web-server

# Terminal 2: Start the container with debug output

container run --debug --name my-web-server registry.example.com/web-test:latest

Inspect boot configuration and log simultaneously:

# View the boot config

container inspect my-web-server --format json | jq .bootConfig

# View the boot log

container logs --boot my-web-server

Search for kernel panics in the boot log:

container logs --boot my-web-server | grep -i "panic\|error\|failed"

Summary

• Boot logs are captured in vminitd.log inside the container bundle, as implemented in MachineBundle.swift and configured by RuntimeService.swift.
• Use container logs --boot to access the VM initialization output; add -f to stream it in real time.
• Check container ps first to confirm the container stopped during boot rather than at runtime.
• Inspect boot-config.json via container inspect to verify kernel paths, network settings, and init-image references.
• Enable --debug for verbose XPC messaging when the boot log lacks sufficient detail.

Frequently Asked Questions

Where is the boot log stored on disk?

The boot log is stored at vminitd.log inside the container’s bundle directory. According to Sources/Services/MachineAPIService/Client/MachineBundle.swift (lines 28–52), this path is defined relative to the bundle root, and the BootLog instance in RuntimeService.swift (lines 73–74) writes all kernel and init-process output to this file during VM startup.

What is the difference between container logs and container logs --boot?

The standard container logs command streams the stdout and stderr of the running container after the VM has successfully booted. The container logs --boot variant reads the vminitd.log file containing the kernel messages and init-daemon output from the VM boot sequence. Use --boot to diagnose failures that occur before the containerized application starts.

How do I debug a container that stops immediately after creation?

Run container ps to confirm the container status is stopped. Then execute container logs --boot <name> to view the boot log and identify the specific failure point. Common causes include malformed boot-config.json entries, missing kernel features, or invalid init scripts, all of which appear as errors in the boot log.

Why does my container fail with a kernel error in the boot log?

Kernel errors in the boot log typically indicate missing host virtualization support or incompatible kernel configuration. The apple/container framework requires an Apple M3 or newer host with a kernel that exposes virtualization capabilities. Check the boot log for messages regarding hardware detection failures or nested virtualization errors, and verify your host meets the documented prerequisites.

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