# How to Troubleshoot Container Startup Failures and Access Boot Logs in apple/container > Troubleshoot apple/container startup failures using container logs --boot to access vminitd.log and view kernel init process output during VM startup. - Repository: [Apple/container](https://github.com/apple/container) - Tags: how-to-guide - Published: 2026-06-22 --- **Use `container logs --boot ` 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`](https://github.com/apple/container/blob/main/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`](https://github.com/apple/container/blob/main/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: ```bash 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: ```bash 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: ```bash 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: ```bash container logs --boot my-web-server | grep "failed to mount" ``` ### Step 3: Validate the Boot Configuration The boot configuration file [`boot-config.json`](https://github.com/apple/container/blob/main/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: ```bash container inspect my-web-server --format json | jq .bootConfig ``` Alternatively, access the file directly if you know the bundle path: ```bash 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: ```bash 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:** ```bash container logs --boot -f my-web-server ``` **Search for a specific init script identifier:** ```bash container logs --boot my-web-server | grep custom-init ``` **Inspect the boot configuration that was used for the VM:** ```bash container inspect my-web-server --format json | jq .bootConfig ``` **Re-run with explicit debugging output:** ```bash 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`](https://github.com/apple/container/blob/main/MachineBundle.swift) and initialized in [`RuntimeService.swift`](https://github.com/apple/container/blob/main/RuntimeService.swift). - Use `container logs --boot ` 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`](https://github.com/apple/container/blob/main/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`](https://github.com/apple/container/blob/main/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`](https://github.com/apple/container/blob/main/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 ` 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 `. 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.