QSWAT+ watershed delineation errors | SWATGenX

QSWAT+ delineation is where many SWAT+ projects stall: the GUI can look “finished” while the Watershed/Shapes folder is incomplete, or the stream network contains topological cases that SWAT+ cannot route. SWATGenX addresses the same cases in preprocessing code — merging divergence==2 reaches, dissolving catchments that lack VAA flowlines, and enforcing single-outlet subbasins before HRU generation.

Where delineation sits in the SWATGenX → QSWAT+ run

SWATGenX drives QGIS and QSWAT+ in an automated server-side run. Each job starts with setup: inputs are prepared, QSWAT+ is launched, and routing is chosen for the outlet and delineation context. When the run uses predefined watersheds, SWATGenX follows the NHDPlus-HR network—reaches and catchments from that fabric supply the hydrography. When that path does not apply, the workflow falls back to TauDEM delineation and builds a terrain-derived drainage network instead. Both branches then complete the same QSWAT+ project build: create reaches and catchments, define HRUs, and write the project files the SWAT+ toolchain consumes.

SWATGenX controls QSWAT+ execution through a server-side QGIS/QSWAT+ environment. The primary path uses a preprocessed NHDPlus-HR routing fabric; when existing-network delineation is not applicable or fails, the workflow falls back to TauDEM and re-enters the QSWAT+ project-building sequence. Outputs are validated before packaging.

Topology: divergence and loops

In NHDPlus_preprocessing.creating_watershed_dissolving_divergence, reaches flagged with Divergence == 2 are merged downstream and removed from the active set so the network does not contain self-contradicting splits that break routing builders.

If you see odd polygons or “missing” streams in a manual build, compare your stream table to the VAA: orphan catchments (no flowline) are explicitly dissolved into the nearest catchment that does have a stream so HRU landscapes still correspond to real channels.

Multiple outlets per subbasin

SWAT+ subbasins are not arbitrary GIS polygons — each logical basin needs a single exit. NHD_SWATPlus_Extractor._enforce_single_outlet_per_subbasin walks basins that still have more than one outlet and merges secondary branches into the downstream basin until the condition holds (bounded by max_rounds). In a manual workflow this often shows up as unexplained QSWAT crashes or Editor import errors.

Concrete file checks (from SWATGenX production code)

The function check_qswat_model_files walks Watershed/Shapes and requires subs1.shp, rivs1.shp, hrus1.shp, hrus2.shp, lsus1.shp, lsus2.shp. That mirrors what experienced modelers manually verify — automated here so cloud jobs fail fast with a precise missing file name.

required_files = [
  'subs1.shp', 'rivs1.shp', 'hrus1.shp', 'hrus2.shp', 'lsus1.shp', 'lsus2.shp'
]
# Each must exist under …/MODEL_NAME/Watershed/Shapes/

See it in context on the map

When you screen a basin in SWATGenX, HUC8/HUC12 geometry and stream networks are already aligned to the same national fabric used for model generation — reducing the class of “my streams do not match my boundary” issues that appear late in desktop QSWAT+.

Watershed Explorer: HUC8 footprint with stream network — the same identifiers carried into the SWAT+ build.

Related guides

These pages are written for people hitting friction in desktop SWAT+ / QSWAT+ workflows — linked from methodology and SWAT+ model generation so they are crawlable, not orphaned.

Explore related