# How to Troubleshoot Container Startup Failures and View Boot Logs in Apple Container > Troubleshoot container startup failures and view boot logs with `container logs --boot `. Pinpoint VM boot sequence errors by streaming the vminitd.log file. - Repository: [Apple/container](https://github.com/apple/container) - Tags: how-to-guide - Published: 2026-06-21 --- **Use `container logs --boot ` 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`](https://github.com/apple/container/blob/main/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`](https://github.com/apple/container/blob/main/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: ```bash 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: ```bash 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: ```bash 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: ```bash 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: ```bash container logs --boot my-web-server | grep "custom-init" ``` ### 3. Verify Boot Configuration The VM boot configuration is stored in [`boot-config.json`](https://github.com/apple/container/blob/main/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: ```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)/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: ```bash 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:** ```bash # 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:** ```bash # 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:** ```bash 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`](https://github.com/apple/container/blob/main/MachineBundle.swift) and configured by [`RuntimeService.swift`](https://github.com/apple/container/blob/main/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`](https://github.com/apple/container/blob/main/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`](https://github.com/apple/container/blob/main/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`](https://github.com/apple/container/blob/main/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 ` to view the boot log and identify the specific failure point. Common causes include malformed [`boot-config.json`](https://github.com/apple/container/blob/main/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.