How to Submit Safari Bug Reports to Apple Engineers

Encountering bugs in the Safari web browser requires a clear reporting process so Apple engineers can identify and resolve the underlying issues. Users and developers have two primary channels for submitting bug reports: Apple's Feedback Assistant for browser interface and system-level issues, and the WebKit bug tracker for rendering, JavaScript, and web standards issues. This article outlines how to create a minimal reproduction case and submit actionable bug reports through both platforms.

Creating a Minimal Reproduction Case

Before submitting a bug report on either platform, you must isolate the issue. Engineers resolve bugs much faster when provided with a minimal reproduction case (often called a "reduction").

  1. Isolate the Code: Strip away all unnecessary HTML, CSS, and JavaScript until you have the smallest amount of code required to trigger the bug.
  2. Avoid Third-Party Libraries: If possible, reproduce the issue using vanilla JavaScript and standard CSS rather than frameworks like React or Bootstrap.
  3. Host or Package the Files: Save the code as a single .html file, a .zip archive, or host it on a live code-sharing site like CodePen or JSFiddle.
  4. Document the Steps: Write down the exact, step-by-step actions required to trigger the issue, along with the expected result and the actual result.

Submitting Bugs via Feedback Assistant

Use Apple's Feedback Assistant for issues related to the Safari user interface, Safari Extensions, iCloud Tabs, Passkeys, browser crashes, or operating system integration.

  1. Open Feedback Assistant: On macOS, press Command + Space to open Spotlight, type Feedback Assistant, and press Enter. On iOS and iPadOS, the app is available automatically if you are running beta software, or you can launch it by typing applefeedback:// into Safari's address bar. Alternatively, visit the Feedback Assistant website and sign in with your Apple ID.
  2. Start a New Report: Click the compose button to start a new feedback form.
  3. Select the Platform: Choose the operating system where the bug occurs (e.g., iOS & iPadOS, macOS, or visionOS).
  4. Categorize the Issue: Select Safari as the area you are seeing an issue with, then specify the subcategory (such as Page Loading, Extensions, or Crash).
  5. Provide Details: Enter a descriptive title. In the description field, paste your step-by-step reproduction instructions, the expected results, and the actual results.
  6. Attach Files: Upload your minimal reproduction file, screenshots, or screen recordings. Feedback Assistant will often automatically gather a sysdiagnose file from your device; allow it to attach this data, as it contains crucial system logs.
  7. Submit: Click Submit. You will receive a Feedback ID (starting with "FB") which you can use to track the status of your report.

Submitting Bugs via bugs.webkit.org

Use the WebKit Bugzilla tracker for issues related to the core web engine that powers Safari. This includes bugs in HTML parsing, CSS layout and rendering, Web APIs, DOM manipulation, and JavaScript execution.

  1. Access the Tracker: Navigate to bugs.webkit.org in your web browser.
  2. Create an Account: If you do not have an account, click New Account in the top navigation bar and follow the verification steps.
  3. Search for Duplicates: Before filing a new bug, use the search bar to see if the issue has already been reported. If it exists, you can add your reproduction case to the existing thread.
  4. Initiate a Bug Report: Click File a Bug on the main page.
  5. Select the Product: Choose WebKit from the list of products.
  6. Choose a Component: Select the specific component that best matches your bug (e.g., CSS, Layout and Rendering, JavaScriptCore, DOM, or WebGL). If you are unsure, select New Bugs.
  7. Fill in the Bug Details:
    • Summary: Write a concise, technical summary of the bug. Include [Safari] or specific platform tags if the bug only happens in a specific environment.
    • Description: State the exact Safari and OS versions you are using. Provide the steps to reproduce, actual results, and expected results. Mention if the code works correctly in other browsers like Chrome or Firefox.
  8. Attach the Reproduction Case: Under the Attachment section, upload your standalone .html file or .zip archive. If you are using an online editor like CodePen, paste the URL in the description, though uploading a static file directly to the bug tracker is strongly preferred by engineers so the code is permanently archived.
  9. Submit the Bug: Click Submit Bug. Your report is now public, and WebKit engineers will triage, comment on, and update the status of the ticket directly on the platform.