Saturday, April 14, 2018

High Sierra Help Breakage

Christian Tietze:

If you run macOS 10.13 High Sierra, try not to use the Help menu. It will appear to freeze the app for which you invoke the Help menu: it will not accept keyboard input anymore, emitting the NSBeep “invalid action” sound in most circumstances.

The reason seems to be that the nifty Search bar inside the Help menu will acquire focus so you can search for a menu item or help book entry. This is taking away focus from the app window.


You can fix this inconsistent state yourself: open the Help menu again, then hover over an adjacent main menu entry, like “Window”. This will apparently close the Help menu in a different, proper way, unlike clicking back inside the main app’s window.

Howard Oakley:

Somewhere between High Sierra 10.13 and 10.13.4, Apple has made major changes to the Help system. Unfortunately, these include radical changes in the undocumented file used by the Help system in ~/Library/Caches/

Those changes not only break my utility HelpHelp, but the information now accessible in those and other Help system files no longer contains that on which HelpHelp relies.

Update (2018-04-15): Daniel Jalkut:

Christian filed a bug, and shared a workaround: set the delegate of the Help menu to your app’s delegate, and listen for the “menuDidClose” delegate method. If it’s the Help menu, restore focus manually.

I generalized this workaround to an approach that should work for whatever window, and whatever responder is currently focused when the Help menu is opened. By saving the window and the responder at “menuWillOpen” time, it can be precisely restored afterwards[…]

Update (2018-04-17): Howard Oakley:

At some stage, between the release of macOS High Sierra 10.13 and the latest update to 10.13.4, Apple has replaced its Help system. I have checked through Apple’s release notes, including those concerning the SDK changes for developers, and have been unable to find any reference to such changes.


Another more pervasive change is the way in which these files refer to Help books. Previously this used their signatures, such as, which made it difficult for the Help system to cope with multiple versions of apps with different Help books. Now each Help book is known by a name which combines that signature with the app’s version number, such as*2.2.2.


Without watching the performance of helpd and HelpViewer over a period of time in the log, it is difficult to draw any firm conclusions as to the practical effects of these changes in 10.13.4. However, simply opening a traditional local Help book shows some quite radical differences, suggesting that this is the largest overhaul of the Help system for some years.

3 Comments RSS · Twitter

Ah, that explains what I was experiencing the other day... I thought my keyboard had locked up.

This bug is especially annoying for me because I have the Help menu mapped to a keyboard shortcut, which lets me easily use menu commands without taking my hands off the keyboard. For seldom-used-but-known commands — e.g. inserting a page break in Pages — using the Help shortcut with a few keystrokes is easier than having to memorize or manually navigate the actual menu.

It’s little features like these that make me dread switching away from macOS, but if Apple goes ahead and breaks them...

[…] High Sierra’s Broken Help Menu » […]

That is a neat little setup you have configured....I would miss that too. Well, excepting the whole it's already broken thing. :)

Leave a Comment