Bugs are an inevitable part of the development process. Though they can be frustrating to bump up against, you can help squash these sorts of problems quickly by identifying the issue you’re running into, reproducing it, and filing a bug report through Apple’s Feedback Assistant.

Learn more about bug reporting

Learn more about our privacy policy when filing bugs with Feedback Assistant

You should always file feedback for any bugs you find while developing for Apple platforms; after all, we can’t fix problems we don’t know about. But how can you be sure that the information you provide is helpful for triaging the issue, rather than a bug-solving dead end? Here are our top tips for making sure your bug report is clear, actionable, and — most importantly — fixable.

Be clear, direct, and detailed

When logging any new bug report, be as descriptive as you can, starting with a title that clearly describes both the issue and the inciting factor. A title like “Calendar events are missing” leaves out important information like how or why, while a title like “Calendar events on macOS 12.4 are missing after creating a quick event” provides more actionable detail.

Tip: It’s often helpful for bug screeners to understand how issues might affect app development. If you identify a problem while developing your app, include the name and version of your app in both the title and description field — even if you can reproduce the problem in a standalone sample project — and add a link to your App Store record or a TestFlight build.

When writing up your problem, describe each step thoroughly — it’s often helpful to pretend that whoever reads your report has never encountered the app or system you’re writing about. For example, a statement like, “When I create an event in Calendar, it disappears in a moment” omits many of the details necessary to reproduce the issue. Are you creating a Calendar event through the Quick Event button, through Siri, or are you dragging to add a new event? How long is a moment? Did the event disappear after multitasking, or did you remain in the app?

Whenever a bug screener has to pause and consider this kind of question, it reduces the likelihood that your problem can get fixed quickly. Instead, consider how you could describe your bug in detail. For instance, you could write:

1. Click Quick Event button in the Calendar app. 
2. Fill out an event with any title. 
3. Hit Return.

Actual Results: The event appears in the right place in my calendar but then disappears.

Expected Results: The Calendar event should appear and stay on my calendar.

After you fill out your reproduction steps and expected result, consider any additional factors that could influence the problem. Are you signed into iCloud? Do you have any Accessibility settings turned on? Can you reproduce the issue elsewhere in the operating system? The more information you include in the initial report, the faster the screener can triage it effectively and get it over to the right team for a fix.

Add a few visuals

A screenshot or screen recording of the reproduced bug can provide valuable clues — and might include details you may not have considered writing in the description field. If you have an issue with UI, you should always include visuals.

Log the crash

Unfortunately, not all bugs are reproducible or have easy-to-follow steps. For these trickier cases, consider providing logging information like a sysdiagnose; if you’re filing a bug on iPhone or iPad, you can use the Feedback Assistant app to capture one automatically. If you’re filing through Apple’s web portal, you can install profiles to help you manually gather a sysdiagnose.

You can also provide any additional logging relevant to the issue. For example, if you’re experiencing a crash, include your app’s crash logs. If you’re reporting a performance regression, include an Instruments Trace on iOS or iPadOS, or a Sample on macOS.

Create a sample project

Running into an issue while developing an app? Consider isolating the problem into a small sample project or Swift Playgrounds project that compiles. Not only can it help you narrow down the specific bug you’re facing, it’s also one of the easiest ways for bug screeners and engineers to triage the problem. If you can’t produce a full sample project, sample code is also helpful — all additional information that can help narrow down the issue is valuable.

Escalate your report

If you’re a paid member of the Apple Developer Program, Enterprise Program, or MFi Program having a technical issue with one of Apple’s platforms on a production release, consider filing a Technical Support Incident. This is a request for code-level support for Apple frameworks, APIs, and tools when you can’t fix a bug, encounter trouble when implementing a specific technology, or have general questions about your code.

Request technical support