Troubleshooting¶

When something goes wrong, Hydrata reports it in three places. Check them in order, then find your symptom below.

Where to look first¶

The scenario status. Every Scenario shows its lifecycle status: Created, Building..., Built, Queued, Computing (with a progress percentage and ETA), Processing results..., Complete, Error, or Cancelled. Anything that fails ends at Error.
The "Run failed" strip. When a Scenario's latest Run has failed, a red Run failed strip appears in the scenario panel with the exact error message. This message is the most useful thing on the page: read it first, and copy it verbatim if you ask for help. Hovering the Error status in the scenario list shows the same message as a tooltip.
The Tasks panel. Click the Tasks button (checklist icon in the right-hand toolbar) to open the task monitor. It lists every background task: terrain uploads, scenario builds, and runs. Click a task to expand it and read its Log line by line. Use the Failed filter to find what broke.

Elevation upload fails or never finishes¶

Symptom: you upload a terrain file, the layer sits at Creating..., and the task in the Tasks panel eventually shows Failed.

Terrain processing normally takes 3-5 minutes (reproject to UTM, build the hillshade, apply the style). If the task fails, expand it in the Tasks panel: the last log line starting with ERROR: names the underlying cause.

Common causes:

Cause	Fix
File is not a GeoTIFF	Only `.tif` / `.tiff` files are accepted. Export your raster as GeoTIFF from your GIS and re-upload.
No coordinate system in the file	Hydrata reads the CRS embedded in the GeoTIFF to choose the right UTM zone. A file with no CRS tag cannot be reprojected. Assign the correct CRS in your GIS, then re-upload.
Truncated or corrupt file	Large uploads that are interrupted produce unreadable files. Re-export and re-upload.

Downloading global terrain instead?

If you used the globe icon to fetch Copernicus GLO-30 terrain and see a Terrain download failed message, the detail text explains why. The most common cause is drawing too large a box: the maximum is about 200 by 200 km. Re-select a smaller area.

Elevation renders in the wrong place or looks wrong¶

Symptom: the terrain uploads successfully but appears in the wrong location on the map, or the elevation layer renders as a single flat colour.

Wrong location. The CRS tag inside the GeoTIFF does not match the data. Hydrata trusts the embedded CRS when reprojecting to UTM, so a mislabeled file lands wherever the wrong CRS says it is. In your GIS, assign the CRS the data was actually captured in (not just any CRS), re-export, and re-upload.

Flat or strange colours. Hydrata treats the value -9999 as "no data". If your raster marks empty cells with a different sentinel value (for example -32768 or 3.4e38), those cells are treated as real ground elevations: the colour ramp stretches across them and the genuine terrain is crushed into one colour. Worse, those cells become enormous pits or walls in the model. Fix the file before re-uploading:

QGISGDAL

Use Raster > Conversion > Translate, and set Assign a specified nodata value to output bands to -9999. If the empty cells carry a different sentinel value, first reclassify them to -9999 with the raster calculator.

gdal_translate -a_nodata -9999 input.tif output.tif

If empty cells hold a different sentinel value, convert them first:

gdal_calc.py -A input.tif --outfile=clean.tif \
  --calc="numpy.where(A==-32768, -9999, A)" --NoDataValue=-9999

See Elevation for the full input requirements.

Scenario will not build¶

Symptom 1: the Build button complains about a missing field. Before a build starts, Hydrata checks the Scenario has a name, a terrain, a boundary, an inflow or rainfall, a resolution greater than zero, and a duration greater than zero. The validation message names the first missing field; fill it in and build again.

Symptom 2: the build starts, then the status flips to Error. The build assembles your inputs, generates the mesh, and produces the scenario package. The "Run failed" strip carries the failure reason:

Error message	Meaning	Fix
`Could not find Boundary data`	The Scenario has no boundary attached, or the boundary layer is empty.	Draw a boundary polygon and select it in the Scenario. See Define Boundaries.
`Could not find Inflow data`	The Scenario has no inflow attached.	Add a rainfall polygon or surface flow line and select it. See Inflows.
`... nodata cells inside the model boundary ...`	Your elevation raster has gaps (no-data cells) inside the model boundary. ANUGA cannot assign a ground level there, so the build stops before wasting compute. The message counts the offending cells and suggests the fix.	Either fill the gaps in the raster (for example with `gdal_fillnodata`) and re-upload, or redraw the boundary so it stays inside the area your elevation data actually covers.
An error immediately after the build starts, with little detail	The boundary extends beyond the elevation raster, so the terrain cannot be trimmed to the domain.	Redraw the boundary inside the terrain extent, or upload elevation that covers the whole domain.

Mesh too big?

Resolution sets the base mesh triangle size, and finer resolution means many more triangles and a much longer build and run. The run log records mesh_triangle_count, the mesh area, and the average triangle area after each successful mesh build, so you can see exactly what a resolution change did. Start coarse, confirm the model behaves, then refine, ideally with Mesh Regions so only your area of interest gets the fine triangles.

Run stuck in Queued or Computing¶

Symptom: the status shows Queued or Computing and nothing seems to happen.

Work through these checks:

Is it actually progressing? While computing, the status shows a progress percentage and an ETA. A rising percentage on a long simulation is healthy: fine meshes and long durations genuinely take hours.
Has live updating paused? If you leave the page open for a long time, a Live updates paused banner appears in the top-right corner and Hydrata stops refreshing the status. Click Resume polling (or simply refresh the page) to pick the status back up. The Run itself was never affected, only the display.
Has the Run silently died? A background watchdog reviews Runs that have been in an active state for more than an hour. If the compute job behind a Run has died, the watchdog flips the Run to Error with a message explaining why (these messages mention the watchdog). You do not need to do anything for this to happen, but it means a Run that stays "stuck" for many hours with zero progress will eventually resolve itself to Error so you can retry.
Want it gone now? Click Cancel Run. Cancelling works at any phase, including mid-build. A cancelled Run is final: adjust the Scenario if needed, then build and run again.

Note

You cannot archive a Scenario while one of its Runs is in progress. Cancel the Run first.

Run failed¶

Symptom: the status shows Error and the Run failed strip displays a message.

Where to find the details:

The error message is in the "Run failed" strip in the scenario panel, and in the tooltip when you hover the Error status in the scenario list.
The full run log is in the Tasks panel: click the Tasks button, find the run's task, expand it, and read the Log. The log records every phase of the Run, from Run id:<n> created through mesh statistics to the failure itself, line by line.

To run again, click Retry. This resets the failed run so the Scenario can be built and run afresh; a confirmation appears when the reset succeeds. Fix the underlying cause first (see the table in Scenario will not build for the common build-time messages), otherwise the retry will fail the same way.

Reproduce it locally

Every built Scenario produces a downloadable scenario package. If a run keeps failing inside the solver, you can download the scenario package and run ANUGA on your own machine to debug interactively. See Run ANUGA yourself.

Result layers not appearing¶

Symptom: the Run finished, but you cannot see depth or velocity layers on the map.

Check these in order:

Is the status actually Complete? After computing, the Run moves to Processing results... while the result rasters are published as map layers. The three result layers (titled <Scenario name> Depth Max, <Scenario name> Velocity Max, and <Scenario name> Momentum Max) only appear once all three are published and the status reaches Complete.
Did you see the "New layers found" notice? When result layers are added to your open map session, Hydrata tells you new layers were added and that you should save your project. If you do not save, the layers can be missing the next time the map loads. Save the project.
Still missing after Complete? Refresh the page. The layer list is rebuilt on load, which picks up any layer that did not arrive in the live session.
A colleague cannot see the results you can see. Result layers inherit the project's sharing settings, which are synced shortly after publication. Ask the project owner to check the project's member permissions.

See Results for what each result layer contains and how to export it.

Map is slow in the browser¶

Symptom: panning, zooming, or toggling layers feels sluggish.

Turn off layers you are not using. Every visible layer is fetched and drawn. Hillshade plus elevation plus several runs' worth of result layers adds up quickly; keep only the layers you are actively comparing switched on.
Zoom in to your area of interest. Wide views of fine-resolution result rasters request far more data than a focused view.
Mind the model size. Finer mesh resolution means larger result rasters, which means heavier map layers. If you only need fine detail in one place, use Mesh Regions instead of a globally fine resolution.
Browser basics. Use a current version of Chrome, Firefox, or Edge with hardware acceleration enabled, and close other heavy tabs. Map rendering is GPU-assisted, so a browser running without hardware acceleration will struggle.

Still stuck: how to get help¶

Email info@hydrata.com. Include:

the project name and Scenario name
the run status you see (for example Error, or stuck at Computing 40%)
the exact error message from the "Run failed" strip, copied verbatim
the Run id:<n> line from the run log in the Tasks panel, if you can find it
roughly when the Run started

Those details let the team trace your exact Run. For questions about the ANUGA solver itself, the engine is open source: see Why ANUGA for links to the ANUGA community project.