better error message on timeout
in lieu of fixing anything, code cleanup, documentation, and more descriptive errors