This is one of those "document it so that no one else has to go through the same pain as you did"

I spent all afternoon trying to diagnose this GWT exception

... Caused by: One or more exceptions caught, see full set in UmbrellaException#getCauses
... Caused by: IllegalStateException: Should only call onDetach when the widget is attached to the browser's document

It was occurring when a PopupPanel was hidden, and involved a particularly complex widget that used JSNI to integrate with a 3rd party JavaScript library.

Debugging it was a pain, but the solution was simple: My onAttach method wasn't calling super.onAttach.

Sometimes the most confusing errors have the most simple solutions.