18.1 Skip to content

18. Troubleshooting

18.1 General Troubleshooting

  • Check the Log Messages Panel for any logging that indicates what the issue may be. The TUFLOW Viewer logs information into a tabs called "TUFLOW Viewer" and "PyTUFLOW" (depending on the source of the logging). The TUFLOW Plugin (separate to the viewer) also logs information into the "TUFLOW Plugin" tab. More logging can be enabled in the Debug tab in the TUFLOW Viewer Settings

18.2 Errors Upgrading to Version 2026 of the Plugin

  • If you are upgrading to version 2026 of the plugin for the first time, please be aware that this version does not support older versions of QGIS. The plugin should be compatible with QGIS 3.38 or later, or QGIS 3.34.13 LTR if using long term release builds. However, it is recommended to use the latest version of QGIS (or latest long term release) if possible.

18.3 Unrecognised File Format

  • Check TUFLOW Viewer V2 is enabled. Drag and drop behaviour is not supported in the legacy viewer.
  • Check the file format is supported in the viewer and enabled in the TUFLOW Viewer Settings (see General Settings for more information on toggle formats).
  • Check the file is not empty, corrupt, or locked by another program.

18.4 NetCDF Permission Denied Errors

Since HDF5 1.14.0, the HDF5 library has become more string about file locking. This roughly corresponds to QGIS 4.2, but it depends on the platform and installation method.

What this means is that while TUFLOW or TUFLOW FV is running, NetCDF result files cannot be opened in QGIS. Previously, some issues could occur when opening result in QGIS while TUFLOW was running, however this could be circumvented by copying the result files to a temporary location (done automatically by TUFLOW Viewer). The permissions have become even stricter since HDF5 1.14.0, and the file cannot be opened at all while TUFLOW is running (it needs to be opened briefly to recognise it as valid NetCDF file to then copy it).

The strict locking can be disabled, however it is not possible to switch this off once TUFLOW is running. It must be done before TUFLOW is started. To disable the strict locking, the environment variable HDF5_USE_FILE_LOCKING must be set to FALSE or 0 (ref: https://support.hdfgroup.org/documentation). As an example, this should be done in the batch file before TUFLOW is started:

set HDF5_USE_FILE_LOCKING=FALSE

TUFLOWFV.exe my_model.fvc

It is also good practice to set this environment variable before starting QGIS if the results are going to be opened in QGIS while TUFLOW is running. This is important if opening XMDF results while TUFLOW is running. TUFLOW will close the XMDF file after writing each output timestep, if QGIS locks the file, TUFLOW will not be able to write the next timestep. To do this on Windows:

  1. Open OSGeo4W Shell (search for it in the start menu)
  2. Type set HDF5_USE_FILE_LOCKING=FALSE and press return
  3. Type qgis and press return to start QGIS with the environment variable set.

18.5 Results load slowly

  • Network drives can affect performance. Check if copying the data locally improves performance.
  • Check if loading the layer in QGIS without the viewer is also slow. If so, this may indicate a more general issue with the file or QGIS rather than the viewer itself.
  • Check the system memory usage. If page file memory is being used, this can significantly slow down performance.

18.6 Nothing is Showing in the Map

  • Check the temporal properties and temporal controller to ensure that the current time in QGIS is within the time range of the results.
  • Check the layer styling, particularly the minimum and maximum values for the colour ramp.

18.7 Nothing is Plotting

  • Check the Coordinate Reference System (CRS) of the workspace and results. Unless loading TUFLOW FV results, the workspace should not be using spherical coordinates.
  • For time series results (e.g. TPC), ensure the selection tool is toggled on (in the plot window) when trying to make selections.
  • For map output results (e.g. XMDF) and if trying to plot from a vector layer, ensure "Extract from map outputs" is checked on.
  • Ensure you have the correct layer selected in the Layers Panel before trying to plot.

18.8 Python Error Reporting that some ID is not Found and is Being Removed

  • Unfortunately, sometimes a selection can get stuck and even if the selection is cleared, the viewer still is trying to plot from some feature that keeps throwing an error. This can be resolved by opening a new plotting tab, or by opening a new plot window.

18.9 No Layers are Loaded

  • If this occurs for a result such as the TPC, check that there are any valid time series results that can be loaded. TUFLOW will write a TPC file even if there are no valid time series results.
  • Check the results are not empty, corrupt, or locked by another program.