Debugging tips for users

If you are having difficulty either starting VisIt and/or looking at some data files once VisIt is running, try some of the following...

Add '-debug 5' to the command-line to launch VisIt. This will generate debug logs for each executable component VisIt is running in the directory that VisIt was launched from.

Note that VisIt runs much slower with debugging turned on. So, it is best to use it only when you need to. VisIt supports debug levels 1-5. Debug level 1 will impact performance the least but also provides the least amount of debug output. Debug 5 will impact performance the most but will also produce the most detailed debug output. If VisIt's performance in generating debug logs is a real problem, you can always try debug level 1 first. If the logs don't show sufficient detail to diagnose your problem, you can re-run at higher debug levels.

On Windows systems, there is an option from the Programs menu to run VisIt with debug logging turned on.

  Start->Programs->VisIt <version>->VisIt with Debug logging.  

Or you can modify the desktop shortcut by right-clicking it so you can modify the "Target" text field of the shortcut and include '-debug 5' after the close double quote (") at the end of the existing string. Also, don't forget to remove it after you have completed debugging because running with debugging turned on causes VisIt to run much slower. Alternatively, you can make a copy of the shortcut icon, naming it something like "visit_debug" and modify only the copy.

VisIt supports 5 levels of debugging. So, each component will generate 5 different debug logs. The level 5 logs have the most information.

If you are running VisIt in a client/server scenario, then only the gui and viewer components will be running locally on your desktop. The other components will be running on whatever system you launched them on. In this case, debug logs for those components will be generated in your login directory on those systems.

Once you have generated debug logs, searching for the string 'Exception' in them can often lead you to clues regarding the problem. But, be aware that there are many cases where Exceptions are 'normal' in that they do NOT lead to a failure to startup or run correctly. So, don't be mislead by these.

Problems with startup can usually be found in the viewer logs (e.g. viewer.5.vlog). Problems with opening a file are usually found in the mdserver logs (e.g. mdserver.5.vlog) and problems with getting a particular plot to work are usually found in the engine logs (e.g. engine_ser.5.vlog or engine_par.###.5.vlog). On Unix, the log files are placed in the directory you fired up VisIt in. On Windows, the notion of a "current working directory" is less strong, and the debug files are placed in .../Documents/VisIt <version>, where <version> represents the version of VisIt. If you are running client-server and the server is on a remote machine, the log files for the server-side processes are placed in your home directory on the remote machine.

In some cases, the problems may be such that the failing components get relaunched. When this happens, the existing logs can get overwritten by new ones. For this reason, VisIt attemtps to keep track of the 5 most recently written logs using a capital letter as the first letter in the log filenames. Logs beginning with 'A' are the most recent and logs beginning with 'E' are least recent. You may need to paw through a few of these logs befor you find what you are looking for. Another option to disambiguate logs from different runs is by adding the command line argument '-pid' to the command to launch VisIt. This will cause the debug logs to be named with process ids so they don't get overwritten. Be aware that doing this can lead to hundreds of log files after many attempts to start/run VisIt. To find the log showing the original problem, you need to sort the logs according to time of modification.

Finally, if you are unable find clues as to what is going wrong, try sending the level 5 logs to visit-users@ornl.gov along with as much information about your situation (version of VisIt, platform type, operations attempted) as possible and we may be able to identify the issue.