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

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 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 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 " indicates a failure in the runtime initialization sequence. In 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. 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 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.

Practical Code Examples

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

// 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:

# 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 when crashes persist.

Frequently Asked Questions

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

Bootstrap failures occur when 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 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.

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