# How to Report Bugs in apple/container: A Step-by-Step Guide > Learn how to report bugs in apple/container with this step-by-step guide. Gather details, use the bug report template, and provide clear reproduction steps for faster resolution. - Repository: [Apple/container](https://github.com/apple/container) - Tags: how-to-guide - Published: 2026-06-30 --- **To report a bug in apple/container, gather your environment details (macOS version, Xcode version, and CLI version), create a new issue using the Bug report template, and fill in the reproduction steps, expected behavior, and actual behavior.** The apple/container repository provides a structured process for filing effective bug reports. According to the source code, the project maintains a dedicated guide at [`docs/bug-report-how-to.md`](https://github.com/apple/container/blob/main/docs/bug-report-how-to.md) and a GitHub issue template at [`.github/ISSUE_TEMPLATE/01-bug.yml`](https://github.com/apple/container/blob/main/.github/ISSUE_TEMPLATE/01-bug.yml) to ensure maintainers can reproduce issues quickly. ## What Information You Need to Collect Before opening a new issue, you must gather specific environment data and logs. The bug report guide in [`docs/bug-report-how-to.md`](https://github.com/apple/container/blob/main/docs/bug-report-how-to.md) specifies three critical categories of information. ### Environment Details Run the following commands to capture your system configuration: ```bash # Record macOS version sw_vers # Record Xcode version xcodebuild -version # Record container CLI version container --version ``` ### Reproduction Steps and Logs Capture verbose output using the debug flag. If the container started but failed later, retrieve its logs: ```bash # Run the failing command with debug output container --debug create --name test-app ubuntu:latest # Capture logs if the container exists container logs test-app > test-app.log ``` Include the exact commands you executed, all flags and arguments, and any relevant log excerpts or exit codes. ## How to Submit a Bug Report Follow these steps to submit a complete bug report using the official template. 1. **Navigate to the Issues tab** of the `apple/container` repository and click **New issue**. 2. **Select the Bug report template** (this automatically loads the [`.github/ISSUE_TEMPLATE/01-bug.yml`](https://github.com/apple/container/blob/main/.github/ISSUE_TEMPLATE/01-bug.yml) structure). 3. **Fill in the template fields**: - Paste the reproduction commands inside a fenced code block. - Describe the current (buggy) behavior versus the expected behavior. - Attach the output from `sw_vers`, `xcodebuild -version`, and `container --version`. - Include relevant log sections from your debug output. 4. **Review and submit** the issue after verifying all required fields are complete. ## Example Bug Report Format When writing your issue description, format the content exactly as shown below to match the template structure: ```markdown **Steps to reproduce** 1. `container --debug create --name test-app ubuntu:latest` 2. `container start test-app` **Actual behavior** ``` failed to bootstrap container test-app ``` **Expected behavior** Container starts and prints its ID. **Environment** - macOS: [output of sw_vers] - Xcode: [output of xcodebuild -version] - container CLI: [output of container --version] **Logs** ```bash # paste relevant portion of test-app.log here ``` ``` ## Key Files and Resources The following files in the repository provide authoritative guidance on the bug reporting process: - **[`docs/bug-report-how-to.md`](https://github.com/apple/container/blob/main/docs/bug-report-how-to.md)** – The complete guide covering environment checks, log collection, and report structure. - **[`.github/ISSUE_TEMPLATE/01-bug.yml`](https://github.com/apple/container/blob/main/.github/ISSUE_TEMPLATE/01-bug.yml)** – The GitHub issue template that structures new bug reports with required fields. - **[`docs/command-reference.md`](https://github.com/apple/container/blob/main/docs/command-reference.md)** – Reference documentation for CLI commands including `container --debug` and `container logs`. ## Summary - **Gather environment data** using `sw_vers`, `xcodebuild -version`, and `container --version` before filing. - **Capture debug logs** by appending `--debug` to your failing command or using `container logs`. - **Use the Bug report template** located at [`.github/ISSUE_TEMPLATE/01-bug.yml`](https://github.com/apple/container/blob/main/.github/ISSUE_TEMPLATE/01-bug.yml) to ensure consistent formatting. - **Include exact commands and log output** in fenced code blocks to help maintainers reproduce the issue without clarification. ## Frequently Asked Questions ### Where is the official bug report guide for apple/container? The official guide is located at [`docs/bug-report-how-to.md`](https://github.com/apple/container/blob/main/docs/bug-report-how-to.md) in the repository root. This file contains detailed instructions on preparing environment information, collecting logs, and structuring your report according to the project's standards. ### What commands should I run before submitting a bug report? You must run `sw_vers` to get macOS details, `xcodebuild -version` for the Xcode version, and `container --version` to record the CLI build. These three outputs provide the baseline environment information required by the issue template in [`.github/ISSUE_TEMPLATE/01-bug.yml`](https://github.com/apple/container/blob/main/.github/ISSUE_TEMPLATE/01-bug.yml). ### How do I capture debug logs for a container issue? Append the `--debug` flag to any `container` command to generate verbose output, such as `container --debug create --name myapp image:tag`. If the container started but exhibits runtime issues, use `container logs ` to capture the log output for inclusion in your report. ### What is the difference between the bug report guide and the GitHub issue template? The [`docs/bug-report-how-to.md`](https://github.com/apple/container/blob/main/docs/bug-report-how-to.md) file is a comprehensive guide explaining *why* and *how* to collect information, while [`.github/ISSUE_TEMPLATE/01-bug.yml`](https://github.com/apple/container/blob/main/.github/ISSUE_TEMPLATE/01-bug.yml) is the structured form that appears when you create a new issue on GitHub. The guide teaches you to prepare the data; the template ensures you enter it in the correct fields.