Mac OS X related sites | Mac OS X Speed FAQ | Directory FAQ

Mac OS X disk directory FAQ
 


Old links to index-site.com need to be updated to macmaps.com.
This FAQ has been written as it is a frequently answered question how to repair your disk directory.

* Special note for Disk Warrior users at bottom of FAQ *
Important exception notes many people forget:
1. You MUST backup your data prior to repairing anything. Issues which require software based repair frequently appear to have the same symptoms as a dying hard drive.
2. You can't repair the directory (Repair Disk function of Disk Utility) of the current boot drive. You must boot off a CD, or connect the drive via target disk mode that you wish to repair the directory of.
3. You can't repair permissions while booted from CD, except in Mac OS X 10.4 or later.
Given those exceptions visit these sections to find the type of repair you need to perform:
4. A dying hard drive and a damaged directory can have identical symptoms. As such, not having a backup would leave you in a catch-22 situation if both the directory and the hard drive are in bad shape, leaving you only with a data recovery firm (see my aforementioned backup your data link for more info on data recovery). Prosoft Data Rescue with an external Firewire hard drive of greater size can recover information from a dying hard drive as long as the directory is in good shape. Disk Warrior and Disk Utility (Repair Disk and its cousin fsck) can repair a directory of a healthy hard drive. Norton Utilities Speed Disk and Disk Doctor starting with Mac OS 8.1 and later has had a Russian Roulette possibility of damaging the directory, and even more so with Mac OS X.

5. The release of Mac OS X 10.5 (Leopard) has rendered all but Apple's Disk Utility and the hardware test volumes that shipped with the Mac (not that shipped with AppleCare) as safe to repair the hard. That means Disk Warrior, Techtool Pro are all awaiting Leopard compatible updates, and as of the last writing of this FAQ on October 26, 2007, they are not.<

10.3 and above have built-in Defragmentation

A very good series of discussions on Ars Technica discuss defragmentation on 10.3 and above. Coming from Windows and Mac OS 9, you may have been used to running Speed Disk or another defragmentation program. If you are defragmenting to have room for very large files, it is recommended to partition your hard disk so you have a second partition that is used as a scratch partition to store large files while you work with them instead of using a separate defragmentation utility. Then when you are done editing, that partition can be erased without touching the boot partition while running the boot partition. Partitioning though does require backing up your data, and if done with Disk Utility, requires erasing the hard disk. See my backup FAQ for more details on backing up. In addition, Apple has a good discussion about what is defragmented on its Knowledgebase Article 25668.
 

Special note for 10.3 users

With Mac OS X 10.3 repairing your directory is a little hairy since symptoms of a bad directory may be indicative of having been bitten by the firewire bug if the problem is with an external hard drive being invisible. If your external hard drive becomes invisible after leaving it mounted on your desktop during a restart, shutdown, or an unsuccessful wake from sleep forcing a restart, or a kernel panic forcing a restart, you should assume that the firewire bug has bitten you, and you should not run any disk utility repair programs, and instead get a compatible hard disk case or firmware for your existing case as is mentioned in the firewire bug link. If you need to recover data, information about that is in the link.
 

When to run Disk Utility

When to repair the disk directory, and what is the disk directory -
First off, you should not run a directory repair on a system that isn't backed up, unless you have no choice. To learn more about backing up, see this FAQ on backing up. Note, you can sometimes recover your data with Prosoft Engineering's Data Rescue when no directory repair utility works. However, this is not something you should rely on, since outside of that, and having no backup, data recovery firms cost thousands of U.S. dollars. The most important thing is to backup first, before attempting to repair the directory.

The disk directory should be repaired anytime you are forced to shut down or restart the computer using the power switch instead of the Apple menu (the Apple menu is the one with the Apple logo in the far left corner of the top white or gray bar of the screen).
If an application suddenly stops responding, your first response may be to improperly restart the computer. Don't! This will cause the directory a certain amount of damage since shutting down the computer properly involves cleaning up many system items. You can hit the command-option-escape key sequence (where command is the key with the Apple logo and cloverleaf logos on the keyboard), on an Apple keyboard to force quit the offending application that has hung. It will not save data that program has worked on once it is force quit, but will give you the chance to properly shut down the computer.

Also if your hard disk is more than 85% full, you should clean up the hard drive of unneeded files. Having an overflowing hard drive can cause the directory to get corrupted. These can be any files in your Home directory that you have stored yourself. Do not touch content in any other folders in Mac OS X other that folders you create in your own Home directory without consulting a technician first. Most of the iApps let you delete unnecessary files directly from the programs themselves, and they store files in Home folder's Pictures, Movies, Music, and Documents folder by default. The Library folder is for Mac OS X use only, though bookmark and mail stored documents frequently find themselves either there or in the Documents folder. You can delete no longer used applications in the Applications folder if they are third party. Any Apple applications should be left alone. Custom create your own folder in the Finder by using the File menu's New Folder command to save any documents you want to open with word processors, spreadsheets, or databases. If you do not follow Mac OS X's file structure, it will make it more difficult in the future to clean up files should you find your hard disk is overflowing with data, and make it more difficult to overcome a directory failure.

In event of a kernel panic you will not have a chance to force quit anything, and a directory may get damaged upon restarting the computer, or may already be damaged.
The directory will be damaged significantly if you get a circle with a slash through it at startup and the computer stalls and won't budge for several minutes. It can also be damaged if you get a flashing ? over a floppy disk icon during startup and that won't budge for several minutes. Either will indicate that the computer can not find your operating system folder or programs, and is frequently indicative of a bad directory, or a bad disk, or a bad connection to the disk. When you get those responses from the system, that's when to attempt to repair the directory.
Note, Norton Disk Doctor and Norton Speed Disk have at random caused disk directories to go bad, and should not be run on any computer that does not have any backup.
Directory repair should only be done to avoid having to spend more time on recovering from backup, but should never be done in lieux of having a backup. Though on rare occasions a directory may be so damaged as to require as much as two weeks to repair. One such case was reported on Apple Discussions board, and the user was using Alsoft Disk Warrior (use version 3.0.3 for Mac OS X 10.4, known as Tiger. Intel Macs can now use Disk Warrior 4.0). The directory is the card catalog that tells the computer where to find files on the computer. You will see its damage when directory repair programs report bad btrees, bad master directory block, bad nodes. Some programs like Disk Utility may not even see the hard disk when the directory is damaged on the hard disk.

Note: Disk Utility may not detect all directory malfunctions, and may incorrectly determine the hard disk is OK, when in fact there are errors only Disk Warrior can fix. If you expect one of the above issues may have caused damage to your directory run Disk Warrior to be certain it has not after making sure you are backed up!
 

How to repair the directory with Disk Utility

Assuming you are not responding to the firewire bug of 10.3, repairing the directory is a simple process. Insert your most recent Mac OS X bootable installer CD and boot off it by starting your Mac holding down the C key.

In some cases holding down the Option key is necessary (instead of the 'C' key) to bring up the CD on a menu you can click the disk icon on the Startup Manager (Intel version, PowerPC version). In Macs that came with 10.7 or later, booting from the recovery disk partition with Command-R and selecting Disk Utility from the on screen menu is required.

The Option key boot is only available on Macs with built-in USB. When using the installer or restore CD that comes with some computers, you will be greeted with the Mac OS X installer and the HD test volume using the Startup Manager. Choose the Mac OS X Install volume on Software Install and Restore disks that come with the same computer, otherwise just choose the Mac OS X install volume if installing from the retail version of Mac OS X. Note you can't run the installer of an older operating system on a machine that came with a newer PowerPC or Intel. Select the right pointing arrow on the screen after selecting the volume in the Startup Manager to launch the installer.

Once your installer program comes on screen, on the upper left corner of the white bar of the screen a boldfaced menu called Installer will become available (in Mac OS X 10.4 the menuitem for Disk Utility has moved to the Utilities menu). Click on that boldfaced menu, and select Disk Utility. Upon entering disk utility, select the hard disk whose directory you want to repair, and click on the First Aid section of Disk Utility. Click then on Repair Disk. In Mac OS X 10.2 and later installers a Repair Permissions is available, and should not be selected unless you have the same version of Mac OS X installed on the hard drive you are repairing as is on the CD. If the CD was a Mac OS X 10.2 installer, it is not the same as having Mac OS X 10.2.3 installed on the computer. Repair Permissions can be run if the disk directory is OK and the computer otherwise won't boot, but you should repair permissions from the Disk Utility found in the Applications -> Utilities folder and not the CD whenever possible.* The Repair Disk button is the only one that impacts the disk directory itself. If after an attempted repair it can't give you a result that "The disk appears to be OK", then you should look at either third party disk repair utilities, or erasing your hard disk and recovering from backup. This is one of the primary reasons it is important to have backup. Two known good backup programs. A well known disk directory repair program for Mac OS X is Alsoft Disk Warrior. Disk Warrior 3.0.3 is the an upgrade that is a must for people using Mac OS X 10.4 (Tiger) with Disk Warrior, and version 4.0 makes it possible to repair the directory on Intel Macs.
 

Special note about repairing permissions

* Repairing permissions is not a directory repair function. However, under certain circumstances it becomes necessary to repair permissions. Mac OS 9 programs are not familiar with the permissions system of Mac OS X, and if the directory is doing well, system functions may not work properly or slow down only because the permissions have gone astray. In addition, anytime you install new software which requires your password, it is possible that the permissions of the system may not be properly kept. As a result it is recommended you repair permissions from Applications -> Utilities -> Disk Utility -> First Aid -> select hard disk on Mac OS X 10.2 or higher whenever finished using Mac OS 9 applications and before and after installing new software.

If you ran repair permissions and were interrupted by a reboot or power outage, you'll need to boot the Mac with an Apple USB keyboard holding command and S keys together. At the prompt type:
diskutil repairPermissions /

If that doesn't work, then look at the other section of repairing the directory with fsck.

For Mac OS X 10.1 users, upgrading to 10.1.5 will give you the ability to run Apple's repair privileges utility which functions the same as Mac OS X 10.2 and above's Disk Utility -> First Aid -> repair permissions.
 

A note about FSCK

The fsck command which you have probably heard about on various discussions board is the same command Apple calls from the Disk Utility when you click Repair Disk on a Mac OS X installer CD's Disk Utility. The difference is that fsck can be run when you don't have a Mac OS X installer CD available to run Disk Utility. If the machine is running Mac OS X 10.3 or higher you need to type /sbin/fsck -fy instead of /sbin/fsck -y to attempt an actual repair. Mac OS X 10.2.8 and earlier don't require this. The one thing it can't do is repair the directory around its own command. So while it is a nice stopgap measure which may work when you don't have an installer CD, you should also attempt to run Repair Disk from the Disk Utility if problems persist. To run fsck, restart the computer holding command-S at startup (where command is the Apple logo key on your Apple keyboard. This shortcut will not work on most third party keyboards, and may not work on the Apple wireless keyboard). A command line screen will appear with instructions to run fsck, and instructions to run mount afterwards. When done type exit followed by a return key.