How to Troubleshoot Container Startup Failures and Access Boot Logs in apple/container

Use container logs --boot <container-name> to view the vminitd.log file stored in the container’s bundle, which captures real-time kernel and init-process output during VM startup.

When a container fails to start in the apple/container project, the root cause typically lies in the virtual machine boot sequence rather than the application layer. Because each container runs inside a lightweight VM managed by the vminitd init process, diagnosing startup failures requires inspecting the specialized boot log that records everything from kernel initialization to init-script execution. Understanding how to access and interpret this log is essential for resolving configuration errors, missing kernel features, or malformed boot parameters.

How the Boot Log Architecture Works

During container creation, the runtime configures a dedicated boot log instance that streams all VM output to a specific file location. In Sources/Services/RuntimeLinux/Server/RuntimeService.swift, the runtime service initializes a BootLog instance that directs output to the bundle’s designated boot log path. The concrete file location—by default vminitd.log—is defined in Sources/Services/MachineAPIService/Client/MachineBundle.swift within the bundle structure.

When the VM launches, vminitd (the init daemon) writes its boot sequence messages, kernel logs, and any early-stage errors directly to this file. If the VM fails to reach a running state, the vminitd.log file contains the diagnostic information needed to identify the failure point, whether it stems from hardware detection issues, filesystem mounting errors, or custom init-script failures.

Viewing Boot Logs with the Container CLI

The primary interface for accessing this diagnostic data is the container logs command with the --boot flag. This command reads the vminitd.log file from the container’s bundle directory and outputs its contents to your terminal.

To view the boot log of a specific container:

container logs --boot my-web-server

Because the log is written in real time during VM startup, you can follow new entries as they arrive using the -f or --follow flag:

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

If the container has successfully booted and you only need to inspect application-level stdout/stderr streams, omit the --boot flag:

container logs my-web-server

Troubleshooting Container Startup Failures

Step 1: Verify the Container State

Begin by checking whether the container reached a running state. Use container ps (or container list) to view the current status. If the state shows stopped immediately after a create or run command, the VM likely failed during the boot sequence, making the boot log your primary diagnostic resource.

Step 2: Inspect the Boot Log Content

Run the boot log command and examine the output for specific error patterns:

• Kernel messages marked with timestamps like [ 0.xxx] ... indicating hardware detection or driver loading issues
• vminitd messages prefixed with info vminitd : ... showing the init daemon’s progression
• Fatal errors such as “failed to mount rootfs”, “cannot find /etc/hosts”, or failures in custom init-scripts

Search for specific error identifiers using standard Unix tools:

container logs --boot my-web-server | grep "failed to mount"

Step 3: Validate the Boot Configuration

The boot configuration file boot-config.json resides in the container’s bundle alongside the log file. Corrupted network settings, invalid kernel paths, or misconfigured --init-image parameters often surface here. Inspect the 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 my-web-server)/boot-config.json

Step 4: Enable Verbose Debug Logging

For deeper insight into XPC message exchanges and runtime operations, enable debug output. Add the --debug flag to your logs command or set the environment variable CONTAINER_DEBUG=1 before running your container operation:

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

Step 5: Confirm Host Virtualization Capabilities

Some startup failures stem from insufficient host hardware support. According to the project documentation, the host must be an Apple M3 or newer with kernel-level virtualization enabled. Verify your system meets these requirements before troubleshooting configuration issues.

Practical Code Examples

Stream the boot log while a container is starting:

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

Search for a specific init script identifier:

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

Inspect the boot configuration that was used for the VM:

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

Re-run with explicit debugging output:

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

Summary

• The apple/container runtime captures VM boot output to vminitd.log inside the container bundle, as defined in MachineBundle.swift and initialized in RuntimeService.swift.
• Use container logs --boot <name> to access kernel and init-process messages, and add -f to follow the log in real time.
• A stopped state immediately after creation typically indicates a VM boot failure requiring log inspection.
• Validate boot-config.json via container inspect when logs suggest configuration errors.
• Ensure the host is an Apple M3 or newer with virtualization support, as hardware limitations can prevent VM initialization.

Frequently Asked Questions

Where is the boot log stored in apple/container?

The boot log is stored as vminitd.log inside the container’s bundle directory. The path is defined in Sources/Services/MachineAPIService/Client/MachineBundle.swift, and the file is populated by the init daemon during VM startup with output from Sources/Services/MachineAPIService/Server/MachinesService.swift.

Why does my container immediately show as stopped after creation?

This typically indicates the VM failed to complete its boot sequence. When container ps shows a stopped state after create or run, inspect container logs --boot <name> for kernel panics, missing filesystem errors, or init-script failures that occurred during the initialization phase.

How can I follow boot logs in real-time during container startup?

Append the -f or --follow flag to the boot log command: container logs --boot -f <container-name>. This streams the vminitd.log file as the VM writes to it, allowing you to watch the boot progression and catch errors as they occur.

What host requirements are necessary for container startup?

The host must be an Apple M3 chip or newer with kernel-level virtualization capabilities enabled. The apple/container runtime relies on hardware virtualization features that are not available on older Apple Silicon or Intel-based Macs, which will cause immediate startup failures visible in the boot logs.

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