adding cache file documentation and fixing errors handling