improved error reporting and documentation