hydromodpy.core.exceptions

Typed exception hierarchy for HydroModPy.

Canonical source for every *Error raised by the package. All exceptions inherit from HydroModPyError, which carries optional sim_id and run_id context plus a code class attribute used by the CLI to map failures to exit codes and stable user-facing messages.

See architecture_cible/13_coherence_globale.md §1.5 for the canonical code assignments. Codes follow the HMPY.Exxx convention.

Exceptions

BackendError([message, sim_id, run_id])	Matplotlib / PyVista backend failure.
CacheCorruptionError([message, sim_id, run_id])	Cache hit with an invalid fingerprint or unreadable payload.
CalibrationError([message, sim_id, run_id])	Calibration loop failure.
CatalogError([message, sim_id, run_id])	DuckDB catalog failure.
CheckpointError([message, sim_id, run_id])	Checkpoint read/write failure.
ConfigError([message, sim_id, run_id])	Configuration loading, validation, or resolution failure.
ConfigMissingError([message, sim_id, run_id])	A required configuration section or key is missing.
ConfigValidationError([message, sim_id, run_id])	Pydantic validation error surfaced as a typed exception.
DataCacheError([message, sim_id, run_id])	Local cache corruption or inconsistency.
DataContractViolation([message, sim_id, run_id])	A dataset does not satisfy its declared contract.
DataError([message, sim_id, run_id])	Input data loading, validation, or provenance failure.
DataSourceError([message, sim_id, run_id])	Remote data source (HTTP/FTP) refused or returned invalid data.
DisplayError([message, sim_id, run_id])	Figure rendering failure.
ExportError([message, sim_id, run_id])	Exporter (NetCDF / CSV / VTU / GeoTIFF) failed to serialise results.
ExtractError([message, sim_id, run_id])	Result extraction failed after a successful solver run.
FigureNotFoundError([message, sim_id, run_id])	Requested figure name is not registered.
HydroModPyError([message, sim_id, run_id])	Base class for all HydroModPy exceptions.
ImplicitInferenceError([message, sim_id, run_id])	Data inference triggered a type not whitelisted in strict mode.
IncompatibleCapabilitiesError([message, ...])	Requested capability is not implemented by the selected solver.
IncompatibleMeshError([message, sim_id, run_id])	Two meshes expected to be congruent are not.
JournalError([message, sim_id, run_id])	Workflow journal write/read inconsistency.
LedgerError([message, sim_id, run_id])	Pipeline ledger (run history) corruption or write conflict.
MeshError([message, sim_id, run_id])	Mesh generation or consistency failure.
MeshGenerationError([message, sim_id, run_id])	Mesh generator (gmsh / FloPy helper) failed to produce a valid mesh.
MissingForcingError([message, sim_id, run_id])	Required climatic / hydrometric forcing is absent for the period.
NetworkError([message, sim_id, run_id])	HTTP 5xx, 429, or timeout while fetching a remote dataset.
ObjectiveError([message, sim_id, run_id])	Objective function evaluation failure.
OptimizerError([message, sim_id, run_id])	Optimizer backend (CMA, Optuna, ...) raised an unrecoverable error.
PipelineError([message, sim_id, run_id])	Pipeline orchestration failure.
ResultsError([message, sim_id, run_id])	Results / postprocessing failure.
ResumeError([message, sim_id, run_id])	Pipeline cannot resume (incompatible checkpoint / config drift).
ResumeIntegrityError([message, sim_id, run_id])	A completed-step artefact failed integrity verification on resume.
SchemaVersionTooNewError([message, sim_id, ...])	TOML schema version is newer than the installed HydroModPy.
SolverBinaryError([message, sim_id, run_id])	Solver binary missing, unreadable, or crashed before producing output.
SolverDivergedError([message, sim_id, run_id])	Solver reported non-convergence.
SolverEnvironmentError([message, sim_id, run_id])	Solver runtime environment (PATH, licences) is misconfigured.
SolverError([message, sim_id, run_id])	Solver execution failure.
SolverInputError([message, sim_id, run_id])	Invalid or inconsistent package data passed to the solver.
SolverMassBalanceError([message, sim_id, run_id])	Mass balance residual exceeds the acceptance threshold.
SolverTimeoutError([message, sim_id, run_id])	Solver exceeded the configured wall-clock budget.
StepError(step_name, cause, *[, run_id, sim_id])	A pipeline step raised an unrecoverable error.
StorageError([message, sim_id, run_id])	Catalog or Zarr storage failure.
UnitAliasConflict([message, sim_id, run_id])	Duplicate / conflicting unit alias registration.
UnknownFieldError(name, available, *[, ...])	Requested field name is not registered in the canonical field registry.
WorkflowDAGCycleError([message, sim_id, run_id])	The workflow DAG declaration contains a dependency cycle.
WorkspaceLockedError([message, sim_id, run_id])	A concurrent process holds the workspace lock.
ZarrStoreError([message, sim_id, run_id])	Zarr store read/write failure.