Common issues, what they mean, and how to resolve them.
The plugin did not load. HydraStorm loads automatically when Civil 3D starts; no manual loading step is required. If the command is unknown:
%ProgramFiles%\Autodesk\ApplicationPlugins\HydraStorm.bundle (default install) or %AppData%\Autodesk\ApplicationPlugins\HydraStorm.bundle (if you chose "Install for me only"). If it is missing, re-run the installer.HydraStorm doesn't remember a window position between sessions — it opens centered on screen every time — so it isn't lost off in unreachable space the way a position-persisting app can be. If you don't see it, check that it isn't simply behind the Civil 3D document window (Alt+Tab), and confirm the HYDRASTORM command actually ran (watch the command line for errors). If it still won't show, capture a diagnostic bundle (see below) and send it to support.
Loops in storm drain networks are not supported. Open Drawing → Network Issues (toolbar) to identify the offending pipe. Common cause: a pipe whose From and To structures cross over a confluence creating a circular flow path.
Not itself an error — a standing list of drawing/project conditions worth reviewing before you trust the numbers. Rows click-navigate to the structure or pipe involved. It covers, among others: mis-labeled or unassigned reference alignments, connectivity problems, pipe geometry that blocks its sub-network, flow-direction warnings, adverse stubs, basins assigned to a structure that no longer exists, inlet bypass targets deleted from the drawing, inlets carrying a type id the active library no longer has, a gutter cross-section not applicable to the assigned inlet type, and a pond drawn as a single pass-through structure instead of the required two (see HydraLink Integration).
A rational-mode storm whose return period has no usable IDF table row or coefficient fit refuses to compute rather than silently returning a dry, "compliant" system — on the storm-first engine that storm alone is withheld (its results, rows, and compliance verdict are all absent; other storms are unaffected), on the legacy engine (no per-storm storm configuration) the whole run stops with a project-scoped error. Either way the message names the storm. Fix it by adding the missing IDF row or coefficient fit for that return period (Project Settings > Hydrology > IDF Curves), or by removing the storm from every module that runs it.
A rational hydrology mode (Manual, or HydraLink on the Basin Parameters basis) can't be trusted when a linked HydraLink pond connects to a structure HydraStorm models — storage attenuates flow, ΣC·A does not. The message names the pond and offers to link the companion solved .hlresults file for the same plan (found automatically), which carries the pond's routed outflow instead. Never delete the pond to get past this — the storage is real. See Project Settings > Why OK Can Refuse.
The inlet module reads each structure's peak flow as the LOCAL gutter flow arriving there. With Accumulate Flows off (Peak Flows Only or HydraLink Fixed Flows mode), the entered value is instead the already-accumulated total for that structure, which the inlet module cannot rate correctly — so the combination is refused as a project-scoped calculation error. Turn Accumulate Flows on, or run the project in a rational hydrology mode.
The normal-depth solver could not find a stable depth within the iteration limit. Causes:
If none of the above resolves it, capture a diagnostic bundle (see below) and send it to support. The iteration limit and convergence tolerance aren't exposed in any dialog, but they are per-user values in %LocalAppData%\HydraStorm\settings.json (MaxIterations, default 100; ConvergenceTolerance, default 0.001) if you need to raise them by hand.
The project is in a rational hydrology mode (Manual, or HydraLink on the Basin Parameters basis), where Q comes from the ΣCA · Cf · I accumulation alone, and the named structures are still carrying a directly entered or imported peak flow. Those flows contribute nothing, so computed Q at and below them is lower than it was when the flows were governing. Fix it by modelling the contribution as drainage area and C, by clearing the leftover flow (switch the hydrology mode to Peak Flows Only temporarily, blank the value in the Hydrology Table, and switch back — rational modes hide the flow column), or — if the numbers come from a routed HydraLink model — by switching the link to the Fixed Flows basis. The warning lists the first five structures and then a count of the rest. See What Enters the Rational Accumulation.
Surcharge has reached or topped a structure rim. The compliance check flags this when HGL Cover (configured in Project Settings) is violated. Resolution: enlarge upstream pipes, increase slope, or adjust the structure rim.
HEC-22 / iSWM / municipal loss equations are evaluated dynamically. If the upstream geometry produces a K value the published table can't represent, HydraStorm marks the cell yellow in the Excel export and writes the literal computed loss instead of the lookup. The number is correct; the spreadsheet just can't round-trip it.
Most often a locked drawing: another command is running or the document is read-only. Check the Civil 3D command line for the underlying error. If a single pipe fails, the rest of the batch still applies; check the calculation messages banner.
Run Output ▾ > Apply Label Styles… from the toolbar, pick the pipe and structure label styles in the dialog, then click Apply. See Profiles & Labels.
HydraStorm hides data-shortcut'd networks (typically water/sanitary) from the analysis dropdown to avoid accidentally analyzing them. They are still loaded for crossings detection. To analyze a referenced network, promote it to a local network in Civil 3D first.
Basin names in HydraLink and structure names in C3D differ enough that even the fuzzy tiers can't bridge the gap. Open the HydraLink import dialog to manually map basins to nodes; that mapping is remembered for future imports. The matcher tries, in order: a persisted mapping from a prior import, the Civil 3D handle, an exact name match, a normalized match (stripped prefixes), a substring match, a close-spelling match, then spatial proximity. There's no separate "manual" tier — a mapping you set by hand becomes the persisted mapping the next import starts from.
The watcher detected an edit on disk. Click the prompt to reload, or ignore it if you're staging changes. The reload re-runs basin matching but preserves your manual overrides.
The workbook is built entirely in code, row by row, with live formulas wherever a formula can reproduce what the engine computed. Yellow highlight marks the exceptions, where HydraStorm writes its own computed number as a literal instead because no cell formula can reproduce it:
The literal value is the correct hydraulic answer in every case. If you re-edit the spreadsheet, a yellow cell will not auto-recompute.
A dialog with this title means a bug in HydraStorm threw an exception the session would otherwise not survive. HydraStorm catches it, logs the full stack, and keeps Civil 3D running — but from that point HydraStorm's own internal state is unknown, so the dialog's instruction is the right one: save your drawing and reopen HydraStorm before continuing to edit. The dialog shows only once per distinct failure per session (repeats are still logged, just not re-prompted). Logs are written to %LocalAppData%\HydraStorm\logs; attach the day's log file when you report it to support. A host (Civil 3D/AutoCAD) exception never shows this dialog — those are left to Autodesk's own error handling.
For any unresolved issue, run Help > Run Diagnostic (HSDIAG) from the toolbar. This generates a Markdown dump of your project state, network topology, and calculation output. Email the resulting file to support@bezaleldesignlab.com.
Email support@bezaleldesignlab.com with the diagnostic bundle and a description of what you were doing.