With Mac OS X 10.7 “Lion”, Apple added a second “content mode” to NSTableView: View-based table views. This allows you to simply create your list items as separate views that get reused and reshuffled to simulate scrolling, instead of using the classic approach of “rubber stamping” a more lightweight NSCell repeatedly into the window. If you’ve programmed for iOS before, this is essentially like UITableView works, just for the Mac.

While this works fairly well most of the time, as of this writing it has one severe bug: Occasionally, a view-based NSTableView‘s view hierarchy gets corrupted in some odd way, causing it to hit an assertion and throw an exception. The main message you see in that case is:

Row 1 should be in the valid visible section.

I don’t know what exactly happens, but it happens if you call -reloadData on your table view too early. Now “too early” may sound a little weird, as cell-based NSTableViews work just fine, but for example the view-based content mode doesn’t like getting a -reloadData from the -awakeFromNib method of the controller that loaded it with its NIB/XIB file.

Doing this early on makes sure that your table view breaks, even if it still seems fine afterwards as long as it is empty. As soon as you add items, however, it croaks. Also, sometimes you don’t need to call the method directly. Just get someone else to call it for you, e.g. by setting the automaticallyPreparesContent property on an NSArrayController.

Thanks to:
brettper, who filed a reproducible case in Apple’s bugreporter and posted it on OpenRadar.
Jacob Gorban, who made the connection to the NSArrayController issue.