update documentation and error reporting