# Troubleshooting Steps for Common Container Errors in the apple/container CLI

> Fix common container errors with apple/container CLI. Learn troubleshooting steps like enabling debug mode, checking system logs, and verifying image availability.

- Repository: [Apple/container](https://github.com/apple/container)
- Tags: how-to-guide
- Published: 2026-07-11

---

**Enable debug mode with `container --debug <command>`, check system logs via `container system logs`, and verify image availability with `container images list` to diagnose most failures.**

The `apple/container` repository provides a Swift-based command-line interface for orchestrating lightweight macOS virtual-machine containers. When errors occur across the CLI, runtime, or networking layers, systematic **troubleshooting steps for common container errors** help you identify the root cause and restore functionality quickly.

## CLI Parsing and Command Execution Errors

Errors originating from the command layer typically present as `error: unknown option` or `invalid argument` messages. These failures occur in `ContainerCommands/*` modules such as [`ContainerRun.swift`](https://github.com/apple/container/blob/main/ContainerRun.swift) before the system invokes any runtime operations.

To resolve these issues, run the command with `--debug` to reveal the full flag parsing flow, or use `--help` to verify accepted parameters. Ensure you are using the correct syntax for macOS 26, as the CLI requires specific entitlements and platform versions.

## Image Handling Failures

When you encounter "image not found" or "failed to pull image" errors, the issue resides in the image management layer. The [`ContainerAPIService/Client/Archiver.swift`](https://github.com/apple/container/blob/main/ContainerAPIService/Client/Archiver.swift) file defines the `ImageError` enum (`public enum ImageError: Swift.Error…`) to categorize these failures.

Verify the image exists locally by running `container images list`. If the image is missing, use the `-f` or `--force` flag to ignore cache warnings during pull operations, as documented in the command reference.

## Bootstrap and Runtime Start Errors

The message "failed to bootstrap container <id>" indicates a failure in the runtime initialization sequence. In [`Sources/Services/Runtime/RuntimeClient/RuntimeClient.swift`](https://github.com/apple/container/blob/main/Sources/Services/Runtime/RuntimeClient/RuntimeClient.swift), the `bootstrap` method throws `ContainerizationError(.invalidArgument, …)` when the runtime cannot establish the container environment.

Enable verbose logging by prepending `--debug` to your command to capture the full XPC request flow. The bootstrap process also writes diagnostic data to `/var/log/container/…` via `ServiceLogger.bootstrap`, which you can inspect with `container system logs`.

## Networking Configuration Errors

Network failures such as "cannot attach to vmnet" or "network not found" originate in `NetworkVmnetHelper+Start.swift` and [`RuntimeLinux/Server/RuntimeService.swift`](https://github.com/apple/container/blob/main/RuntimeLinux/Server/RuntimeService.swift). These errors occur during the network-bootstrap validation phase.

Note that macOS 15 disables custom vmnet networks, making `container network` commands unavailable on that version, as detailed in the technical overview documentation. If you see network-related failures on macOS 15, remove the `--network` flag and use the default networking stack.

## Permissions and Entitlements Failures

"Operation not permitted" or "failed to set entitlements" errors indicate insufficient privileges or missing code signatures. The installer uses configurations defined in `signing/*.entitlements` files, while runtime checks occur within `ServiceLogger.bootstrap`.

Ensure you installed the package with administrator rights, allowing the `sudo` prompt to complete during installation. Verify the installation by checking that the service appears in `launchctl list | grep com.apple.container`.

## System Service Communication Issues

When the CLI reports "container system not running" or "cannot communicate with service", the [`ContainerPlugin/ServiceManager.swift`](https://github.com/apple/container/blob/main/ContainerPlugin/ServiceManager.swift) module cannot reach the background daemon. This file manages the service lifecycle using `launchctl bootstrap` and `launchctl kickstart` commands.

Check the service status with `launchctl list | grep com.apple.container`. Restart the service using `container system restart` to resolve transient communication failures.

## Diagnostic Workflow for Root Cause Analysis

Follow this systematic approach to isolate container failures:

1. **Run with debug output** – Execute `container --debug <command>` to print the full request/response flow and any underlying `XPCMessage` errors.
2. **Check system logs** – Run `container system logs` to view service log files containing timestamps, categories, and `ServiceLogger` messages.
3. **Inspect container logs** – Use `container logs <container-id>` to retrieve stdout and stderr from the specific container process.
4. **Validate the environment** – Confirm you are running macOS 26 (the only supported version) and using a signed package by running `sw_vers` and `container --version`.
5. **Re-run with minimal flags** – Strip optional arguments like `--network` to isolate the failure point, particularly on macOS 15 where custom networking is restricted.
6. **Collect full error information** – Copy the exact error text, exit code, and any stack traces into a bug report following the guidelines in [`docs/bug-report-how-to.md`](https://github.com/apple/container/blob/main/docs/bug-report-how-to.md).

## Practical Code Examples

When building custom tooling around the container runtime, handle bootstrap errors explicitly:

```swift
// Example: handling a bootstrap error in custom tooling
import ContainerAPIService

func startContainer(id: String) async throws {
    do {
        let client = try ContainerClient()
        try await client.bootstrap(id: id, stdio: [], dynamicEnv: [:])
        print("✅ Container \(id) started")
    } catch let err as ContainerizationError {
        // The error includes a code and human-readable message
        print("❌ Bootstrap failed: \(err.message) (code: \(err.code))")
        // Re-throw or handle as appropriate
        throw err
    }
}

```

Capture comprehensive logs from the command line:

```bash

# Capture detailed logs for a failing container

container --debug run myimage --name test

# If the command exits, fetch the logs

container logs test > test.log

# Also dump system-wide logs

container system logs > sys.log

```

## Summary

- **Enable debug mode** (`--debug`) to expose detailed error information from the CLI through the runtime layer.
- **Check system and container logs** using `container system logs` and `container logs <id>` to view bootstrap and runtime output.
- **Verify image availability** with `container images list` before attempting to run or pull containers.
- **Restart the system service** via `container system restart` when encountering "system not running" errors.
- **File detailed bug reports** using the template in [`docs/bug-report-how-to.md`](https://github.com/apple/container/blob/main/docs/bug-report-how-to.md) when crashes persist.

## Frequently Asked Questions

### How do I fix "failed to bootstrap container" errors?

Bootstrap failures occur when [`RuntimeClient.swift`](https://github.com/apple/container/blob/main/RuntimeClient.swift) cannot initialize the container environment via the `bootstrap` method. Run `container --debug run <image>` to see the underlying `ContainerizationError` details, then check `container system logs` for messages from `ServiceLogger.bootstrap` in `/var/log/container/`.

### Why do I see "cannot attach to vmnet" errors on macOS 15?

macOS 15 disables custom vmnet network interfaces, which causes networking commands to fail. The `NetworkVmnetHelper+Start.swift` module validates these capabilities during startup. Remove the `--network` flag from your commands to use the default networking stack instead.

### What should I do when the container system service is not responding?

When [`ContainerPlugin/ServiceManager.swift`](https://github.com/apple/container/blob/main/ContainerPlugin/ServiceManager.swift) cannot communicate with the daemon, verify the service status with `launchctl list | grep com.apple.container`. If the service is missing or stopped, run `container system restart` to trigger a fresh `launchctl bootstrap` sequence.

### Where are error logs stored for debugging?

The `ServiceLogger` implementation writes bootstrap and runtime errors to `/var/log/container/…`. Access these logs using the `container system logs` command, or inspect individual container output with `container logs <container-id>` for process-specific stderr and stdout.