Troubleshooting guide

[Jon Stovell]

Note: In the following steps, replace DriveName with the actual name of the drive in question.

1. Rerun the “Choose Drives…” setup and make sure DriveName is included.

Running the setup again wipes out any old settings for DriveName and creates new ones in their place. This should ensure that everything is configured the way it is supposed to be. In most cases, this will resolve any issues.

If Keep Drive Spinning completes the setup successfully, but you still have problems with your drive falling asleep even after doing this, proceed to step 2.

2. Click the “More…” button, select “Run Diagnostic”, and then select DriveName from the list.

The diagnostic will conduct a series of tests to determine whether the Keep Drive Spinning launch agent is working correctly for the selected drive—and if not, why not. It will detect and report most common reasons for trouble.

1. If the diagnostic reports that the Keep Drive Spinning launch agent for your drive is working correctly, then…
1. If you set a custom update interval to something relatively long (e.g. 300 seconds) and your drive is falling asleep, click the “More…” button and select “Customize update schedule” to change to the interval to something shorter. The default suggestion of 60 seconds should work well for healthy drives from all known manufacturers.
2. If your drive is falling asleep even with an interval of 60 seconds or if it is having other issues of some sort, the problem is not a bug in Keep Drive Spinning. Instead, the problem lies elsewhere, and Keep Drive Spinning cannot help you with whatever it is.
   
   You should consider the possibility that your drive may be malfunctioning. If your drive is falling asleep even though Keep Drive Spinning is working, or your drive disconnects itself from Finder, or it loses data, or anything like that, back up your data RIGHT NOW! You may need to repair or replace the drive.
2. If the diagnostic reports that the hidden file on the drive, named .keepThisDriveSpinning, cannot be modified, then…
1. The drive may be read-only. Read-only drives cannot be kept awake using the method that Keep Drive Spinning uses. If it is possible to attach the drive to your computer with read and write permissions, try doing that.
2. You may not have the necessary permissions. The diagnostic tool will open the Finder’s information window for the hidden file so that you can investigate and correct the problem.
3. The hidden file may be locked. The diagnostic tool will open the Finder’s information window for the hidden file so that you can investigate and correct the problem.
3. If the diagnostic reports that the drive is not currently configured to be kept awake, or that the hidden .keepThisDriveSpinning file on the drive does not exist, then…
1. Go back and do step 1 for real this time. ;-)
4. If the diagnostic reports that the launch agent is not working and that it cannot determine why, there may something unusual going on that tripped up Keep Drive Spinning. Read over the information that the diagnostic reported to see if anything stands out. Possible causes include, but are not limited to, the following:
1. Keep Drive Spinning has not been granted the necessary access permissions in the Security & Privacy preference pane in System Preferences. If this is the case, the diagnostic tool itself will not be able to run any tests. Open the Security & Privacy preference pane in System Preferences, go to the Privacy tab, and grant Keep Drive Spinning the access permissions it needs. Depending on the version of macOS, you may need to grant access to the disk and/or permission to control Finder.
2. The drive has a name with strange or unexpected characters that managed to trip up the code. This should not happen, but if it does, it is a bug in Keep Drive Spinning that I want to know about and fix. Proceed to step 3 below.
3. The drive has a faulty connection to your computer. Try completely disconnecting and then reattaching the drive. If you are connected to the drive over a wireless network, move somewhere with a stronger signal.
4. The drive is damaged. Damaged drives can become erratic and unpredictable. Recover whatever data you can and replace the drive.
5. The drive has a file format or uses a connection method that is not normally supported by macOS. You are on your own dealing with that, you crazy hacker. ;)
6. The operating system itself has a bug that interferes in the way it interacts with your drive, even though the drive’s file system is supported. The diagnostic tool will report such problems if any occur. Such a problem is not a bug in Keep Drive Spinning, but I still want to hear about it in order to see if a workaround is necessary and possible.  Proceed to step 3 below.
   
   Note: This scenario is unlikely, but not impossible. For example, a handful of users reported that macOS’s included touch command, which Keep Drive Spinning used to update the hidden file in versions prior to 2.0, inexplicably failed with errors for their drives—even when manually run as the root user! (I could never reproduce the problem, but several users reported it independently. This was part of the reason Keep Drive Spinning 2.0 switched away from touch to another command.)

3. If appropriate, file a bug report.

If the result of working through the diagnostic report in step 2 led you to conclusion 4.b. or 4.f., you may have an appropriate reason to submit a bug report. To put together a useful bug report, please include the following:

1. A brief description of the problem.
2. The full output you got from the diagnostic tool.
3. Any other information that might be useful.