Search Developer

---

1. Bug Header Information

i. Product

Choose the product or software where the problem originates. If these specific details are not provided, choose “Mac OS X” or “Other” in the product list.

x. Classification

Setting the appropriate classification for the bug helps us properly classify the priority of the problem. The following are the Classification options and definitions:

• Security: Potential security exposures
• Crash/Hang/Data Loss: Bugs which cause a machine to crash, resulting in an irrecoverable hang or loss of data
• Power: Issues pertaining to power consumption and battery life
• Performance: Issues that reduce the performance or responsiveness of an application
• UI/Usability: A cosmetic issue or an issue with the usability of an application
• Serious bug: Functionality is greatly affected, and there is no workaround
• Other bug: A bug that has a workaround
• Feature (new): Request for a new feature
• Enhancement: Request for an enhancement to an existing feature

ii. Reproducibility

Let us know how frequently you are able to reproduce this problem.

iii. Version/Build Number:

Provide the version and build of the OS or application. To obtain this information in Mac OS X, select “About this Mac” from the Apple menu. Next, click on the version number listed under “Mac OS X.” You will then be able to view the build number.

Back to Top

---

2. Bug Title & Description

i: Problem Report Title:

The ideal problem title is clear, concise, succinct and informative. Note: This field is limited to 80 characters. The ideal title includes the following:

1. Build or version of the software or OS on which the problem occurred
2. Verb describing the action that occurred
3. Explanation of the situation that was happening at the time that the problem occurred
4. In case of a crash or hang, include the symbol name

When creating a title, we also recommend the following guidelines:

• Be objective and clear; refrain from using colloquialisms/slang.
• Include keywords or numbers from any error messages you may be receiving.
• Avoid using vague language such as ‚Äúfailed,‚Äù ‚Äúuseless,‚Äù ‚Äúcrashed,‚Äù etc.

The following examples demonstrate the difference between a non-functional title and a functional title:

	Non-functional title	Functional title
Example 1	Application Crashed	9C7010: Finder crashed connecting to iDisk
Example 2	iMovie completely fails	iMovie 7.1.1 fails with error when exporting to QuickTime

ii: Description:

Include a Summary, Steps to Reproduce, Expected Results, Actual Results, Workaround, and Regression/Isolation.

Summary:

Recap the problem title and be explicit in providing more descriptive summary information.

• Provide what happened, what you were doing when it happened, and why you think it‚Äôs a problem.
• If you receive an error message, provide the content of the error message or an approximation of it.
• Provide specifics and refrain from using vague language or colloquialisms.

Instead of using descriptive words or phrases when something “looks bad,” “has issues,” “is odd,” “is wrong,” “is acting up,” or “is failing,” be concise and describe how something is looking or acting, why you believe there is a problem, and provide any error messages that will support the problem being reported.

	Non-functional	Functional
Example 1	When printing, nothing happens. Application doesn’t work.	Print Menu item enabled, print dialog box appears, print button enabled, but progress dialog box doesn’t appear.
Example 2	Safari is slow.	Safari is slow allocating JavaScript arrays. (Also provide a Shark sample and sample JavaScript.)

Steps to Reproduce:

Describe the step-by-step process to reproduce the bug, including any non-default preferences/installation and the system configuration information. Note: It is better to include too much information than not enough, as this minimizes the amount of back-and-forth communications. Be very specific and be sure to provide details, opposed to high-level actions.

• Important points to note when providing steps to reproduce are:
  • When does the problem occur?
  • Does it occur after log-out?
  • Does it occur after relaunch?
  • Does it occur after shutdown?
• Where is the home directory that you‚Äôre working from?
  • Is this a regular local home directory?
  • Is this a portable home directory on an external drive?
  • Is this a network home?
• What type of user is it that is in question?
  • Is it a standard user?
  • An admin user?
  • Is it a managed client user?
• Be sure to include any Accessibility features that you‚Äôre using (such as VoiceOver, keyboard navigation), as well as stipulating whether you‚Äôre using the keyboard or the mouse to navigate.
• Include information about any preferences that have been changed from the defaults.

	Non-functional	Functional
Example	Opened a file.	Double clicked on a file to open it.

Expected Results:

Describe what you expected to happen when executing the steps to reproduce.

Actual Results:

Explain what actually occurred.

Workaround:

If you have found a workaround for this problem, describe it.

Regression/Isolation:

Note any other configurations in which this issue was reproducible. Include details if it is new to this build or no regression testing was done.

Back to Top

---

3. Additional Information Requirements (General)

Reports should include, at minimum, a complete System Profiler report showing pertinent configuration information (essential when reporting hardware-related issues). Additionally, the appropriate log files are essential when reporting crashing issues, kernel panics, or any other failures or error messages. Below is a list of frequently required files stipulating the scenario in which each respective file is needed.

1. If reporting an issue with hardware, or general failure issues, Include a System Profiler report
2. If reporting a crashing bug, a Crash Log is required
3. If reporting a kernel panic, a Panic Log is required
4. If reporting a hang, freeze, or performance issues, a sample and/or Shark profile is required
5. If reporting an error dialog message or UI bug, provide screen shots

i: System Profiler report (.spx file)

To obtain a System Profile Report, select “About This Mac” from the Apple Menu and click the “More Info” button. This automatically launches the System Profiler application. Once the System Profiler application has been launched please follow the steps below.

1. Select “Save” from the File menu
2. Keep the format as “System Profile”
3. Click the “Save” button
4. Append the file to your bug report

A System Profiler report can also be obtained via Terminal using the following command:

/usr/sbin/system_profiler -detailLevel full -xml >mymachine.spx

This command will create a full System Profiler report, named “mymachine.spx,” which will open in System Profiler on another machine.

NOTE: A full System Profiler report provides vital information from the user’s hardware configuration (drive, audio, Bluetooth, graphics, and external hardware information), to networking configurations (including wireless, firewall, location networking, internal modem and volume information), to software configurations (including installed applications, extensions and fonts, frameworks, preferences, and access, console, error, install, mail, Software Update, and system log files).

ii. Crashing Issues

If a crash has occurred, a crash log is essential. To locate the crash log in Tiger (10.4) or later, check the following location:

~/Library/Logs/CrashReporter
/Library/Logs/CrashReporter

If you are not able to locate any crash report information in either of these locations, check the /var/log/system.log for any relevant error messages from “crashreporter” or “crashdump.”

iPhone crash logs can be obtained by following the instructions below.

NOTE: Only include one crash log per bug. If you’re able to reproduce the crash the exact same way each time and the crashing thread looks identical in every instance, only one crash log is required. This allows us to efficiently distribute the necessary information to Apple Engineering. In instances where the crash doesn’t look identical, file separate reports with one crash log submitted per bug.

* See TN2123 for information on the anatomy of a crash log.

iii. Kernel Panic

If a kernel panic has occurred, a panic log is required. Backtraces are saved to nvram, then copied to the panic.log file on restart. This file can be located in /Library/Logs.

* See TN2063 for information on the anatomy of a panic log.

iv. Hanging/Performance Issues

If you are experiencing a “hang” (includes freeze, spinning wheel, slowness), a sample of the application while it is in the hung state is required. A sample can be obtained by any of the below options:

Using Terminal

run ‘sample (Application Name) 15’

* The output can be attached directly to your bug report via the “My Originated Problems” section in the Bug Reporter.

Note: The application name must be typed exactly as the application is named; this command line is case-sensitive. After the sampling has been completed, Terminal will supply the file path to the location to which the sample analysis was written.

Using Activity Monitor

• Launch Activity Monitor (/Applications/Utilities/)
• While the application is hung, click on the application to highlight it
• Select View -> Sample Process
• Click Save

Note: more information about using “Sample” may be found on its man page, which can be retrieved by entering “man sample” in the Terminal window.

How to SSH into a machine (from another machine on the same network)

Providing the machine is not hung to the point that you cannot SSH into it, you can do the following from Terminal:

1. ssh (IP address) -l (login account)
2. top
3. Identify the process taking a lot of CPU
4. sample (process ID) 5
5. cp /tmp/* ~/Desktop/
6. Restart the machine and log in as the user you SSH’d into

Note: Use monospaced font for Terminal commands.

Shark:

You must have Shark installed to provide a Shark profile. Steps on how to obtain a Shark sample can be found here. For all of the means of gathering a sample, the sample file will appear on your desktop.

NOTE: If you have an older application called “Sampler” on your system, do not use this. A Shark profile provides more useful information.

v. Screen shots

Provide a screen shot when it will help clarify the bug report. In addition to providing screen shots for error or dialog messages, please type the text of the error/dialog message you are seeing in the description of the bug report (so that the message contents are searchable. If there are steps involved, a sequence of screen shots, or even a movie is always appreciated (but be sure to write down the steps associated with each screen shot).

It is useful to provide a screen shot when:

• Seeing a dialog
• Experiencing rendering or redraw issues
• You are trying to describe an icon or other aspect of the screen and you‚Äôre not sure what it is called

A screen shot can be captured in any of the following ways:

Description	Shortcut
Save a picture of the entire screen	shift-command-3
Save a picture of a selected area of the screen	shift-command-4
Use Preview to capture a screen shot	Launch Preview (/Applications/Utilities/Preview) From the menu, select File->Grab->(type of screen shot)
Use Grab to capture a screen shot	Launch Grab (/Applications/Utilities/Grab) From the menu, select Capture->(type of screen shot)

Back to Top

---

4. Contact Information

Be sure to include current contact information. This will ensure that we’re able to correspond with you as we investigate your issue. This information can be updated by logging into the ADC Member Site and choosing the “Update Profile” page, or by logging into the My Info page.

Back to Top

---

5. Apple Product-specific Additional Information Requirements

For bug reports filed against any of the following Apple products, product-specific information is required in addition to any generic information as stipulated above.

Xcode

When submitting a bug report against Xcode or any of Apple’s other developer tools, be sure to provide the following additional information:

• Mac OS X build number and version:

  Both can be obtained by clicking the “Apple” logo in the menu bar, and then clicking “About This Mac.”

• Xcode IDE build:

  The Xcode build can be obtained by selecting Xcode -> About Xcode.

• gcc and gdb builds:

  These builds can be obtained by entering the following commands in Terminal:

  gcc -v
  gdb -v

  The output for each will contain some of the following information:

  gcc:

  • [stability-drive:~] name% gcc -v
  • Using built-in specs.
  • Target: i686-apple-darwin8
  • Configured with: /private/var/tmp/gcc/gcc-5367.obj ‚Äî target=i686-apple-darwin8
    Thread model: posix
  • gcc version 4.0.1 (Apple Computer, Inc. build 5367)

  gdb:

  GNU gdb 6.3.50-20050815 (Apple version gdb-563) (Wed Jul 19 05:17:43 GMT 2006)

• Sample project/test case that reproduces the behavior. Do not include confidential information.
• Build log
• Temporary files located in [~]/Library/Caches/Xcode Build Directory
• Crash log and sample code for any crashing or hanging issues

Logs can be found at:
~/Library/Logs/CrashReporter/Xcode.crash.log

Note: Use of -save-temps leaves a preprocessed source file on the disk with the following file naming convention:

• .i for C language sourcefile.c
• .ii for C++ language sourcefile.cc
• .mi for Objective-C language sourcefile.m
• .mii for Objective-C++ language sourcefile.mm

Java

When submitting a bug report against Java, be sure to provide the following additional information:

• Java build information:
  • Put the Java build number at the beginning of your title as such:
    1.5.0_06-112: Title Here
  • The java build can be obtained by entering the following command in Terminal:
    java -version
  • The output will look like this:
    java version “1.5.0_06”
Java(TM) 2 Runtime Environment, Standard Edition (build 1.5.0_06-112)
Java HotSpot(TM) Client VM (build 1.5.0_06-64, mixed mode, sharing)
• Test case with clear and concise steps to reproduce that will enable us to reproduce this in-house.

• Crash logs required from both of the following locations:

  [~]/Library/Logs/Java/JavaNativeCrash.crash.log
  [~]/Library/Logs/CrashReporter/JavaCrash.log

• Hanging issues require that two samples be taken while Java is in a hung state. This includes:

  • Java Stack Trace: You will need to obtain the process number using ‚Äútop‚Äù from the Terminal or /Applications/Utilities/Activity Monitor.app. In Terminal, type ‚Äúkill -QUIT pid‚Äù where pid is the process number obtained above. The dump will appear wherever the Java application is set to send its output (either into the Console log, or within the Terminal window if you chose to start the sample from the command line).
  • Native Stack Trace: In Terminal, type ‚Äúgdb attach pid‚Äù. You will receive a gdb prompt that states ‚Äú(gdb)‚Äù. In gdb, type ‚Äút a a bt.‚Äù The results will appear in the Terminal/gdb window.

Safari

When submitting a bug report against Safari or WebKit, be sure to provide the following additional information:

• URL-related issues: If you are experiencing URL-related issues, provide clear details on how the URL is not working, and screen shots which portray the issue. Additionally, be sure to include the URL.
• JavaScript issues: If you are experiencing a JavaScript-related issue, provide the actual JavaScript (or a test case).

Mail

When submitting a bug report against Mail, be sure to provide the following additional information:

• Mail Composition issues: For composition-related issues in Mail, try reproducing in TextEdit and Blot. Blot can be found in /Developer/Examples/WebKit/Blot/. If you are experiencing an issue that only occurs when replying to messages, reply to a message in Mail, do a Select All, copy, and paste it into Blot before proceeding. For reply bugs, it‚Äôs often necessary to provide the message itself. To do that, select the message in the message list, select File -> Save As, Raw Message Source, and provide the raw source with the bug report. NOTE: Raw Message Source is always necessary for display bugs as well.
• Test Account: If you‚Äôre able to provide a test account for reproducible issues, provide that. Being able to log into an account and test the issue is the best way to identify the problem at hand and reach a resolution.
• • Connection Logs: Provide the smallest connection log as possible that captures the issue. Note: Connection logs may contain a lot of spurious information that doesn’t pertain to the issue at hand.

  • Scenario Example

    Mail deletes a message when you try to move it from one mailbox to another on the same IMAP server.

    1. First you want to check Mail to ensure that there’s nothing pending
    2. Select the source mailbox
    3. Quit Mail

    4. Run the below command line:

       /Applications/Mail.app/Contents/MacOS/Mail -LogSocketErrors YES
       -LogActivityOnHost your.mail.server -LogActivityOnPort 143 &>~/Desktop/ConnectionLog.txt

    5. Additionally, if you are on Leopard (10.5) or later, you can run this logging instead:

       /Applications/Mail.app/Contents/MacOS/Mail -LogActivitiyOnHost your.mail.server -LogMaximumBytes 200 -LogIMAPErrors YES &>•/Desktop/ConnectionLog.txt

       (This will cut out a lot of unnecessary personal information that would otherwise be logged.)

  NOTE: ** You will need to populate your IMAP server’s actual hostname and port number where applicable. **

  Also note that “&>” assumes the default shell in Mac OS, bash. And, csh/tsch users will have to say “>&”instead. LogSocketErrors will launch Mail. When Mail is launched, open the Activity panel (Window -> Activity), and once it has died down, drag your message into your mailbox. When the activity is done, quit Mail. That will give you the shortest connection log possible with just the right information required.

• • Mail Plug-ins or system third-party applications enhancers installed:
    If you have any system third-party applications enhancers installed, always remove them and retest the issue you are experiencing before reporting the issue to Apple. Mail plug-ins go in one of the [~]Library/Mail/Bundles/ folders, and third-party applications enhancers can be anywhere (one that is known is iAlert which injects itself into Mail without installing a plug-in).
  • ***NOTE: These plug-ins and third-party applications enhancers are not currently supported by Mail.***
• If your computer setup is slightly non-standard, indicate that in the bug report. (For example, if you‚Äôre using a network or portable home directory, have FileVault on, or if you‚Äôve run out of disk space.)

iChat

When submitting a bug report against iChat, be sure to provide the following additional information:

• iChat version being used
• For issues with other IM clients: Provide the version of the client, and version of the OS and include any logging of over-the-wire activity if appropriate: (Example: If a bug where the text display malformed on the receiving end or vice versa, a tcpflow dump [or Windows equivalent] is useful in determining if the data is being sent correctly. Additionally, Be sure to provide regression information, (i.e., did this always occur with the client or did it start happening after an iChat upgrade/OS upgrade, etc...?))
• Provide details on how you are connected to the Internet. (e.g., Comcast DSL, AirPort hooked into an office LAN, etc....) Be sure to include the brand and model of the router you have for AV-related issues.

• For issues regarding failed video conference attempts, provide the connection log(s) by doing the following:

  1. Quit iChat
  2. Launch terminal
  3. Type in the following command in terminal:
     /Applications/iChat.app/Contents/MacOS/iChat -errorLogLevel 7
  4. Attempt a video/audio chat with the other user
  5. Gather the terminal output from the failed attempt from both users, and provide us with both files.
• In 10.4.8 and later, the connection log can be copied directly from the iChat dialog.
• Additionally, some basic trouble-shooting of ports can help. Make sure you have UDP ports 16384 - 16403 open both ways for UDP traffic. Port 5060 needs to be open for communication in establishing a video/audio chat. Port 3456 is another communication port that we need open.
• Additionally, please take a look at /Applications/Utilities/Console for iChat- or iChatAgent-related error/warning messages and provide us with any details.
• For API issues (AppleScript and our IM Framework), a small sample application or snippet of sample code that demonstrates the problem is required.

In addition to all the above, provide any information regarding what you were doing around the time of the problem.

Audio

When submitting a bug report against audio, be sure to provide the following additional information:

• Reproducible sample case or project
• Hardware drivers (if applicable)
• Audio/speaker settings located in the Sound preference pane (if applicable)

Note: Version and build information can usually be found in the “About” window of the software installed, or in the product literature.

USB/FireWire

When submitting a bug report against USB or Firewire-related issues, be sure to provide the following additional information:

• Power Management (sleep/wake) issues):
  • Be aware of what is plugged into your machine.
  • Be sure to provide a System Profiler while the external drive is connected (if applicable).
  • Tell us the specific type of drive you have (i.e. USB drive, USB flash drive, USB zip, FireWire, FireWire800, etc....)
  • Tell us the specific make, model, and firmware of the drive
• If you have both Intel-based and PPC-based Macs, try to reproduce the issue on both machines and provide us with the pertinent data from both.

Additional information is required for issues specifically filed against AirPort and the iPod. See below for details of what information is required for each.

AirPort

When submitting a bug report against AirPort (for Client Mac or Wireless Base Station issues), be sure to provide the following additional information:

• Type of encryption (WEP, WPA) if any in use.
• Specify if the network is visible or hidden.
• Provide Base station information: If there‚Äôs a possibility that the bug has something to do with wireless base stations (even if your base station is an Apple AirPort Base Station), the make, model, firmware revision, and a summary of the configuration of the unit is required.
  • To obtain the AirPort configuration file in Mac OS X, follow these steps:
    1. Go to /Applications/Utilities
    2. Launch the AirPort Admin Utility application
    3. Highlight & double-click on the AirPort Base Station (the information should be displayed in the field to the right)
    4. Save this configuration as a file, and upload it to your bug report
• Provide AirPort-specific client Information: If there‚Äôs a possibility that the problem has something to do with the client Mac, provide the version of the AirPort client software (the version of the Airport Admin Utility) you have, and how you have the AirPort tab in Network Preferences configured.
  • To obtain the AirPort configuration file in Mac OS X, follow these steps:
    1. The AirPort network settings in Mac OS X can be obtained by doing the following:
    2. Select the Apple menu -> System Preferences

iPhone/iPod touch

You can file a report by logging into the Apple Bug Reporter from iPhone or iPod touch, as well as can update existing reports with information. Note, however, that because file upload is not supported, you will need to upload additional fils from a supported browser on your host system.

If you have experienced a crashing issue with an application on the iPhone, sync your iPhone with iTunes and check the following location on your host machine:

• For Mac Users: /Library/Logs/CrashReporter/MobileDevice/<iPhone name>
• For Windows Users: Application Data/Apple Computer/Logs/CrashReporter/MobileDevice/<iPhone name>

If you experienced a crash and you are not able to locate any pertinent crash report information, provide specific information including what you were doing, any URLs, or addresses that you were searching for at the time of the crash.

iPod

When submitting a bug report against the iPod product line, be sure to provide the following additional information:

• The iPod model against which you are filing a bug
  For help determining your iPod model, visit http://docs.info.apple.com/article.html?artnum=61688.
• The version of iPod software (firmware) currently installed on your iPod For help determining your iPod software version, visit http://docs.info.apple.com/article.html?artnum=60984.

Note: if you have an Apple iPod + HP sold by Hewlett-Packard (HP), HP, not Apple, provides support and service for Hewlett-Packard iPods.

iDVD

When submitting a bug report against an iDVD issues, be sure to provide the following additional information:

• Media:
  • What DVD-R media was used? Include the brand and speed.
  • Have you tried using different media to burn your project? What happened?
• Project Information:
  • How many menus are present?
  • Are these menus customized: yes/no?
  • How many slideshows?
  • How many images in total?
  • What image is the format/size?
  • Is there any DVD-ROM content? If so, what?
  • How many videos, format, source (iMove/FCP/Other Type)
  • Is this an old project you just continue to work on or is it a new project?
  • Was iDVD launched by you or it was launched from iMovie or iPhoto?
  • How did you create the files used in the project?
  • What version of iMovie was used (if any)?
  • What version of QuickTime?
• Complete project file
• Hardware drivers (if applicable)

Back to Top

1. Developer
2. Bug Reporting
3. Best Practices