Error Codes
Case loading reports errors in two groups: validation report kinds
(diagnostic categories collected while the case is validated) and
load-failure kinds (returned when a case fails to load). The page also
lists the policy-load errors a checkpoint refusal raises and the
runtime errors of a running novomodelo run.
How these errors reach you
Seção intitulada “How these errors reach you”Novomodelo surfaces errors through four user-facing channels:
-
novomodelo validatehuman report — errors print aserror:prefixed lines; warnings (after a successful validation) print aswarning:prefixed lines. -
novomodelo validate --json— on success, one JSON object on stdout:{ configured, boundary_date, report }, pluspolicy_load: { mode, unused_stored_bases }when the run would load a policy (modewarm_start,resumeorsimulation_only), with noerrorkey;configuredistruewhenpolicy.boundaryis configured and the run applies it, which only a run that trains does, andfalseotherwise. On failure, those three keys arenulland anerrorkey holds{ phase, message }. Thephasefield is the name of the failingLoadErrorvariant, one of the six preparation-phase kinds, or a policy-load kind (WarmStartIncompatible,ResumeIncompatible,SimulationPolicyIncompatible, orIoErrorfor a checkpoint the OS refuses to read); it names aLoadErrorvariant, a preparation kind or a policy-load kind, never theErrorKindof a collected diagnostic. A case-load failure reportsConstraintErrorin almost every case, because every per-file read, parse and schema failure and every validation rule is collected into one report; itsmessageholds one[<ErrorKind>] <file>[ (<entity>)]: <message>line per collected error, joined by newlines (the[ (<entity>)]part appears only when the error names an entity). Warnings are not in the JSON. Only a missing case directory prints no JSON object; it reports on stderr and exits2.A case with no
policy.boundarysucceeds with:{"configured": false,"boundary_date": null,"report": null}A hydro unit group that names a bus that does not exist fails with:
{"configured": null,"boundary_date": null,"report": null,"error": {"phase": "ConstraintError","message": "[InvalidReference] system/hydros.json (Hydro 0 unit group 0): Hydro 0 unit group 0 references non-existent Bus 99 via field 'bus_id'"}} -
novomodelo.io.validate(...)(Python) — returns{ valid, errors: [{ kind, message }], warnings: [{ kind, message, file, entity }] }.errorsholds at most one entry: none whenvalidis true, one on failure. Itskindis the same string as the CLIphase, and itsmessageis the error’s full text, which for a case-load failure startsconstraint violation:. For a missing case directory, where the CLI prints no JSON object, Python still returns anIoErrorentry. Each warning’skindis theErrorKindname. -
novomodelo.errorsPython exception classes — case loading raisesValidationErrororCaseIoError; a policy-load refusal raises the class of its error:PolicyIncompatibleErrorfor a refused checkpoint or one that is missing or cannot be decoded,CaseIoErrorfor a checkpoint read the operating system refuses, andValidationErrorfor a missing policy directory or a refused boundary reconciliation (see Policy-load errors). Seenovomodelo.errorsfor the full hierarchy and Python Quickstart — Error Handling for catching these classes.
Policy-load failures use different exit codes and exception classes; see How a policy-load failure reaches you. For the cause and fix of the failures a study commonly meets, see Troubleshooting.
Kind index
Seção intitulada “Kind index”Find the kind named on your error line (the word in square brackets, or the phase value of novomodelo validate --json) in the first column; its row gives how the kind is reported, its severity, and the exit code novomodelo returns for it.
| Kind | Reported as | Severity | Exit code |
|---|---|---|---|
FileNotFound | [FileNotFound] report line | Error | 1 |
ParseError | [ParseError] report line; phase value | Error | 1 as a report line; as a phase value, 4 (novomodelo validate) or 1 (novomodelo run) |
SchemaViolation | [SchemaViolation] report line | Error | 1 |
InvalidReference | [InvalidReference] report line | Error | 1 |
DuplicateId | [DuplicateId] report line | Error | 1 |
InvalidValue | [InvalidValue] report line | Error | 1 |
CycleDetected | [CycleDetected] report line | Error | 1 |
DimensionMismatch | [DimensionMismatch] report line | Error | 1 |
BusinessRuleViolation | [BusinessRuleViolation] report line | Error | 1 |
WarmStartIncompatible | phase value (refused policy load); warning: line | Error; Warning | 1 (2 under phase IoError); 0 for a warning |
ResumeIncompatible | phase value (refused policy load); warning: line | Error; Warning | 1 (2 under phase IoError); 0 for a warning |
SimulationPolicyIncompatible | phase value (refused policy load); warning: line | Error; Warning | 1 (2 under phase IoError); 0 for a warning |
NotImplemented | [NotImplemented] report line | Error | 1 |
UnusedEntity | warning: line | Warning | 0 |
ModelQuality | warning: line | Warning | 0 |
SemanticAmbiguity | warning: line | Warning | 0 |
IoError | phase value | Error | 2, including an OS-refused policy read |
SchemaError | phase value | Error | 1, including a policy.path refusal; 4 under novomodelo validate only for the post-report AR-coefficient count mismatch (novomodelo run: 1) |
ConstraintError | phase value | Error | 1 |
ConfigValidationError | phase value | Error | 1 |
StochasticPreparationError | phase value | Error | 1, or 2 for a stochastic-input read such as a declared opening tree that is absent (both subcommands) |
StudySetupError | phase value | Error | 1 |
HydroModelsPreparationError | phase value | Error | 1 |
GenericConstraintValidationError | phase value | Error | 1 |
BoundaryReconciliationError | phase value | Error | 1 |
PolicySoftwareMismatch | policy-load refusal | Error | 1 |
| Stored bases not used | warning: line | Warning | 0 |
Runtime failures carry no kind; Runtime errors gives the exit code of each message.
A solver-profile rejection carries phase StudySetupError, or
BoundaryReconciliationError with policy.boundary configured;
Solver profile validation states its exit code.
Validation report kinds
Seção intitulada “Validation report kinds”Each error a case load collects prints as one report line, [<Kind>] <file> (<entity>): <message>. The
(<entity>) part appears only when the error names an entity, and <Kind> is one of the values below.
novomodelo validate prints each error as error: followed by its report line, and exits 1 when any error is
present. novomodelo run prints error: constraint violation: followed by the same lines. After a successful
validation, novomodelo validate prints each warning as a warning: line of the form <file> (<entity>): <message>
after the Valid case: ... line, without the bracketed kind, and novomodelo.io.validate (Python) returns the
warnings, each with its kind, in its warnings array.
A warning of the policy load the run would apply prints after them as
warning: <output dir>/<policy.path>: <message>, names no entity, and counts in the Validation: line.
The three warning kinds (UnusedEntity, ModelQuality,
SemanticAmbiguity) never stop a run, and neither does a BusinessRuleViolation that novomodelo validate prints as a warning: line; every other report line is an error that must be resolved
before the case loads.
WarmStartIncompatible, ResumeIncompatible and SimulationPolicyIncompatible are not report-line kinds:
each names a refused policy load, as the phase value, and that load’s warnings: WarmStartIncompatible for a
policy.mode = "warm_start" load in a run that trains, ResumeIncompatible for a policy.mode = "resume"
load in a run that trains, and SimulationPolicyIncompatible for the load of a simulation-only run, whatever its
policy.mode; see their entries below.
FileNotFound
Seção intitulada “FileNotFound”Severity: Error
When it occurs: A file that is required by the case structure is missing from the case directory. Emitted when the required files are checked, once for each of them that is not found on disk.
Example: A case directory without system/hydros.json:
[FileNotFound] system/hydros.json: required file 'system/hydros.json' not found in case directoryA case directory without system/buses.json gives two
[FileNotFound] lines: the first reports the missing required file, the second
the failed read of it:
[FileNotFound] system/buses.json: required file 'system/buses.json' not found in case directory[FileNotFound] system/buses.json: No such file or directory (os error 2)Resolution: Create the missing file in the correct subdirectory. The required files are: config.json, penalties.json, stages.json,
initial_conditions.json, system/buses.json, and system/hydros.json.
ParseError
Seção intitulada “ParseError”Severity: Error
When it occurs: A file exists and was read but could not be parsed —
invalid JSON syntax, an unreadable Parquet header, a missing required field, or
an unknown enum variant in a tagged JSON union. Emitted when a file is parsed and the
parse fails. config.json and
system/hydros.json report a missing field or an unknown variant as a
SchemaViolation instead, and
system/hydro_production_models.json does so for an unknown variant.
A training.stopping_rules entry that carries a field that belongs to a different rule type — for example,
seconds (a time_limit field) on a bound_stalling rule — is also rejected
as a ParseError with an unknown field message.
Display format:
parse error in {path}: {message}This format reaches you only for a parse error raised after the validation report is complete (see Load-failure kinds); a parse failure in the report prints as the [ParseError] line shown in the examples below.
Fields:
| Field | Description |
|---|---|
path | Path to the file that failed to parse |
message | Human-readable description of the parse failure |
Example:
[ParseError] stages.json: parse error: EOF while parsing a list at line 2 column 0A missing required field, here a constraint entry without slack:
[ParseError] constraints/generic_constraints.json: parse error: missing field `slack` at line 1 column 69A bound_stalling rule that carries seconds, a time_limit field:
[ParseError] config.json: parse error: unknown field `seconds`, expected `iterations` or `tolerance` at line 19 column 5Resolution: Fix the syntax error in the indicated file. Use a JSON linter
or Parquet viewer to find the exact location. For JSON files, common causes are
trailing commas, missing quotation marks, or mismatched braces. For a
missing field message, add the field it names. For an unknown field message inside a stopping_rules entry, remove the field that does not
belong to that entry’s type, or move it to an entry whose type declares it.
See also: an anticipated_config object in system/thermals.json that matches neither accepted
lead shape is collected under this kind — see
Invalid anticipated-thermal lead.
Unknown field in a generic-constraint entry
Seção intitulada “Unknown field in a generic-constraint entry”When it occurs: Each generic-constraint object accepts exactly five fields
(id, name, description, expression, slack); any other key is rejected
as a ParseError with an unknown field message.
Fields:
| Field | Description |
|---|---|
path | Always constraints/generic_constraints.json |
message | An “unknown field” message, naming the offending key and the five accepted field names |
Example: A constraint object with an extra type key:
[ParseError] constraints/generic_constraints.json: parse error: unknown field `type`, expected one of `id`, `name`, `description`, `expression`, `slack` at line 10 column 12Resolution: Remove the unknown field, leaving only the five accepted keys. See Generic Constraints for the grammar.
SchemaViolation
Seção intitulada “SchemaViolation”Severity: Error
When it occurs: A file parses successfully but a field fails a schema
constraint: a required field is missing from config.json or system/hydros.json, or a required Parquet column is missing (a missing field in any other JSON file is a ParseError), a Parquet file carries a column its table does not list, a value is outside its valid range
(e.g., negative capacity, non-positive penalty cost, a reservoir whose
min_storage_hm3 exceeds max_storage_hm3, or a stage whose num_openings is
0), a field contains an unexpected type, or an entity id appears twice in a
registry file such as system/buses.json. Emitted when the fields of a parsed
file are checked.
Example:
A negative penalty cost:
[SchemaViolation] system/buses.json: field buses[0].deficit_segments[0].cost: penalty value must be > 0.0, got -100A reservoir whose minimum storage exceeds its maximum:
[SchemaViolation] system/hydros.json: field hydros[0].reservoir: min_storage_hm3 (800) must be <= max_storage_hm3 (500)A stage with no openings:
[SchemaViolation] stages.json: field stages[0].num_openings: num_openings must be > 0A config.json without training.selection:
[SchemaViolation] config.json: field training.selection: a forward-pass count is required via training.selectionTwo buses that share an id in system/buses.json:
[SchemaViolation] system/buses.json: field buses[1].id: duplicate id 0 in buses arrayResolution: Correct the value in the indicated field. Field paths use
dot-notation and zero-based array indices. Consult the
Case Format page for valid ranges and required fields.
For storage bounds, ensure min <= max. For opening counts, ensure num_openings >= 1.
For config.json, training.selection (for example
{ "method": "sampled", "forward_passes": 192 }) and training.stopping_rules
are mandatory keys with no default when absent. An absent training.selection is
reported with the message a forward-pass count is required via training.selection; add the key to config.json.
See also: a constraints/hydro_bounds.parquet spillage-band inversion or
non-negativity rejection is collected under this kind during a full case
load — see
Spillage-band inversion.
Two of the four failures of
Invalid anticipated-thermal lead print [SchemaViolation] lines; the
other two print [ParseError] and [BusinessRuleViolation] lines. A case load prints every schema failure
as a [SchemaViolation] line; the schema error in <path>, field <field>: <message> form is the display
format of SchemaError, which reaches you only for a load error raised after the report is
complete.
A generic constraint’s slack object is checked under this kind too, on the
field constraints[<i>].slack.penalty or constraints[<i>].slack.penalty_basis:
an enabled slack needs a positive penalty and a penalty_basis, and a
disabled slack carries neither. The missing-basis message names the choice:
slack.enabled is true but slack.penalty_basis is absent: use "per_hour" for a row in MW or m³/s, "per_unit" for a row in MWh or hm³The other slack messages:
slack.enabled is true but slack.penalty is absentslack.penalty must be > 0.0 when enabled, got {value}slack.penalty is set but slack.enabled is falseslack.penalty_basis is set but slack.enabled is falseA penalty_basis other than per_hour or per_unit is a ParseError
(unknown variant). See
Generic Constraints — Penalty basis.
A computed FPHA’s fit range in system/hydro_production_models.json is checked
under this kind too: an fpha_config.spillage_fit_max_m3s or
fpha_config.turbined_fit_max_m3s that is not a finite number above 0 is
refused on the field
production_models[<i>].stage_ranges[<j>].fpha_config.<name> (or
production_models[<i>].seasons[<j>].fpha_config.<name>):
<name> must be finite and > 0.0, got <value> for hydro_id <id>Configuration load rules
Seção intitulada “Configuration load rules”config.json loading refuses these values; each prints a [SchemaViolation] config.json: field <field>: <message> line, and both commands exit 1.
| Rule | Field | Message |
|---|---|---|
No iteration_limit rule | training.stopping_rules | must contain an iteration_limit rule |
interval_iterations absent or below 1, checkpointing enabled | policy.checkpointing.interval_iterations | must be at least 1 when policy.checkpointing.enabled is true; got {found} |
policy.path naming no subdirectory ("", ., ..) | policy.path | "{value}" names the output directory or one of its ancestors, which a checkpoint write would replace; choose another directory, such as "./policy" |
{found} is no value when the key is absent and 0 otherwise. {value} is the configured policy.path.
Refused policy.path
Seção intitulada “Refused policy.path”When it occurs: policy.path is resolved against --output, and a link is checked where it sits and where it points. The path is refused when it names the output directory or one of its ancestors, or names, contains or lies inside a directory a run rewrites or removes. Configuration — policy states the rule. In a case that trains, the path is refused too when it (for a link, its target) or its .staging or .previous sibling is not a directory or holds an entry no checkpoint writer leaves there; the message is refusing to write a checkpoint: …, quoted under Policy Management — Checkpoint Directory Contents.
"{value}" names the output directory or one of its ancestors, which a checkpoint write would replace; choose another directory, such as "./policy""{value}" {relation} {dir}, which a run removes whole before writing its outputs; choose a directory that neither contains nor lies inside it, such as "./policy""{value}" {relation} {dir}, which holds files a run writes and a checkpoint write would replace; choose a directory that neither names nor contains it, such as "./policy"{relation} is names, contains or lies inside, and {dir} is the output-relative directory, such as simulation/hydros. For a link, {value} reads {path} -> {target}. novomodelo validate reports phase SchemaError (exit 1), or IoError (exit 2) when the path cannot be inspected; novomodelo run prints error: schema error in {path}, field policy.path: {message} and exits 1.
Overlapping seasons in one resolution level
Seção intitulada “Overlapping seasons in one resolution level”When it occurs: Seasons whose spans differ by at most 7 days form one resolution level, and two seasons of one level may not share a calendar day. The load refuses an overlapping pair of season_definitions with [SchemaViolation] stages.json: field season_definitions.seasons: <message>, where <message> is:
seasons {a} and {b} overlap within one resolution level; seasons whose spans differ by at most 7 days form one level and must not share a calendar day{a} and {b} are the ids of the two seasons. Stage Files — stages.json describes season_definitions.
Namespace collision between a scalar parameter and a named expression
Seção intitulada “Namespace collision between a scalar parameter and a named expression”When it occurs: constraints/generic_constraints.json’s expressions
array declares named linear expressions that share the @name reference
namespace with constraints/generic_parameters.json’s scalar parameters. A
named-expression entry whose name matches an already-loaded scalar
parameter’s name is rejected — a @name token must resolve unambiguously to
exactly one kind of thing.
Fields:
| Field | Description |
|---|---|
path | Always constraints/generic_constraints.json |
field | expressions[i].name — the colliding entry’s index |
message | name "<name>" is declared as both a scalar parameter and a named expression; the "@name" namespace is shared |
Example:
[SchemaViolation] constraints/generic_constraints.json: field expressions[0].name: name "demanda" is declared as both a scalar parameter and a named expression; the "@name" namespace is sharedResolution: Rename the named expression (or the scalar parameter) so the
two @name tables do not overlap. See
Generic Constraints for the @name
grammar shared between the two files.
Named-expression reference cycle
Seção intitulada “Named-expression reference cycle”When it occurs: expressions[] entries reference each other by @name;
a cycle in that reference graph (including a length-1 self-reference) is
rejected before any expression is inlined, even if no constraint ever uses it.
Fields:
| Field | Description |
|---|---|
path | Always constraints/generic_constraints.json |
field | Always expressions |
message | named-expression reference cycle detected: <a> -> <b> -> ... -> <a> |
Example:
[SchemaViolation] constraints/generic_constraints.json: field expressions: named-expression reference cycle detected: fnese -> fnese_margin -> fneseResolution: Break the cycle — rewrite one of the named expressions in the
reported chain so it no longer refers back to an ancestor. See
Generic Constraints for the @name
composition rules.
Named-expression inlining term budget exceeded
Seção intitulada “Named-expression inlining term budget exceeded”When it occurs: Inlining substitutes every @name reference with its
referenced expression and folds the result into one coefficient per variable.
An acyclic but exponentially-expanding declaration is caught once the
expansion would exceed 100,000 coefficient operations, far above any
legitimately authored expression, aborting the blow-up before it
materializes. A doubling chain whose links are scaled by a scalar
parameter, @e_k = @a * @e_{k-1} + @e_{k-1}, hits the cap; a chain of plain
self-additions, @e_k = @e_{k-1} + @e_{k-1}, folds to one term per variable
and stays under it. The cap applies only when a constraint (or another
expression) actually references the runaway declaration — declaring it
without referencing it is a cheap existence check, not an expansion.
Fields:
| Field | Description |
|---|---|
path | Always constraints/generic_constraints.json |
field | constraints[i].expression (or the referencing expression’s own field) |
message | `@<name>`: named-expression reference "@<name>" expands to more than 100000 coefficient operations; this indicates an exponential reference pattern (e.g. a doubling chain "@e = @prev + @prev") when the expansion runs inside a referenced named expression, or `<fragment>`: expression expands to more than 100000 coefficient operations when it runs in the referencing expression’s own text, for example @e15 + @e15 |
Example:
[SchemaViolation] constraints/generic_constraints.json: field constraints[0].expression: `@e60`: named-expression reference "@e60" expands to more than 100000 coefficient operations; this indicates an exponential reference pattern (e.g. a doubling chain "@e = @prev + @prev")Resolution: Rewrite the named-expression chain to grow linearly rather
than by repeated self-addition — e.g. accumulate into one running expression
instead of doubling a reference at each step. See
Generic Constraints for the @name
composition rules.
Generic-constraint expression rejected
Seção intitulada “Generic-constraint expression rejected”When it occurs: An expression in constraints/generic_constraints.json
(constraints[i].expression, or expressions[i].expression for a named
expression’s own definition) that the grammar or its linearity rule refuses.
Every message starts with the offending fragment in backticks, as in
`@zz`: unknown name …; a problem at the very end of the text ends in
(at the end of the expression) instead.
| Mistake | Message after the quoted fragment |
|---|---|
An @name declared neither as a scalar parameter nor as a named expression | unknown name "@<name>": no scalar parameter or named expression with this name was declared |
| A product of two terms that both hold LP variables | product of LP variables is not linear; when a factor is a named expression, followed by ("@<name>" is the named expression at expressions[<i>], which contains LP variables) |
| A division by a term that holds an LP variable | division by an expression containing LP variables |
| A constant built from numbers that divides by zero | division by zero |
| A numeric literal too large to represent | numeric literal <text> is not finite |
| A constant part in an expression with no relational operator | an expression without a relational operator cannot have a constant part; put the bound in generic_constraint_bounds.parquet or use <=, >= or == |
| Two relational operators | a generic constraint expression carries at most one relational operator (<=, >=, ==); an inline double-relational range is not supported — split into two constraints |
| A relational operator inside parentheses | a relational operator is only allowed at the top level |
A bare < or > | bare '<' at position <n> is not a valid operator; use '<=' for a relational bound |
| Parentheses and unary signs nested deeper than 256 levels | expression nests deeper than 256 levels |
| A named-expression body with a relational operator | a named expression cannot contain a relational operator |
| A named-expression body that reads no LP variable | "<name>" contains no LP variable; declare it in generic_parameters.json as a kind "expression" parameter |
Fields:
| Field | Description |
|---|---|
path | Always constraints/generic_constraints.json |
field | constraints[i].expression or expressions[i].expression |
message | The quoted fragment followed by one of the messages in the table above |
Example: A product of two LP variables:
[SchemaViolation] constraints/generic_constraints.json: field constraints[0].expression: `hydro_generation(0) * thermal_generation(0)`: product of LP variables is not linearResolution: Keep every term linear: scale an LP variable only by a
number, a scalar parameter or an expression built from them, and divide only
by such a constant. Check that each @name matches a parameter declared in
constraints/generic_parameters.json or an entry of this file’s own
expressions array; move a body that reads no LP variable into
constraints/generic_parameters.json as an expression parameter. See
Generic Constraints — Expression grammar
for the full grammar.
Scalar parameter entry rejected
Seção intitulada “Scalar parameter entry rejected”When it occurs: An entry of constraints/generic_parameters.json whose
fields do not match its kind, or an expression parameter whose formula is
refused. The formula messages start with the offending fragment in backticks,
as for a generic-constraint expression.
| Mistake | Field | Message |
|---|---|---|
A payload field of another kind, such as values on a constant | scalar_parameters[i].<field> | "values" is only valid for kind "per_stage" or "seasonal", not "constant" |
An expression parameter without its formula | scalar_parameters[i].expression | "expression" kind requires an "expression" field |
| An LP variable in the formula | scalar_parameters[i].expression | an LP variable cannot appear in a scalar-parameter expression |
An @name that is not a scalar parameter | scalar_parameters[i].expression | unknown scalar parameter "@<name>"; a named expression cannot appear in a scalar-parameter expression |
| A relational operator in the formula | scalar_parameters[i].expression | a scalar-parameter expression cannot contain a relational operator |
| A constant that divides by zero | scalar_parameters[i].expression | division by zero |
A reference cycle among expression parameters | scalar_parameters | expression-parameter reference cycle detected: <a> -> <b> -> ... -> <a> |
Fields:
| Field | Description |
|---|---|
path | Always constraints/generic_parameters.json |
field | The field named in the table above |
message | One of the messages in the table above |
Example: An expression parameter that reads an LP variable:
[SchemaViolation] constraints/generic_parameters.json: field scalar_parameters[0].expression: `hydro_storage(0)`: an LP variable cannot appear in a scalar-parameter expressionResolution: Give each entry only the payload field of its kind. Build an
expression parameter from numbers and other scalar parameters only, with no
relational operator, and break any cycle among them. A formula over LP
variables belongs in constraints/generic_constraints.json as a named
expression. See
Generic Constraints — expression parameters.
A formula whose value is not finite only at some stage and block is reported
by GenericConstraintValidationError.
Repeated block argument
Seção intitulada “Repeated block argument”When it occurs: A variable takes at most one positional block argument. A second one, equal or not, is rejected when the expression is parsed, for example hydro_turbined(5, 0, 1).
Fields:
| Field | Description |
|---|---|
path | Always constraints/generic_constraints.json |
field | constraints[<i>].expression or expressions[<i>].expression |
message | repeated block argument in variable "{name}", where {name} is the variable, such as hydro_turbined |
Resolution: Give the variable one block argument. See Generic Constraints — Expression grammar for the full grammar.
Unknown Parquet column
Seção intitulada “Unknown Parquet column”When it occurs: A Parquet input carries a column that its table on Case Format does not list. The column names are checked when the file is opened, before any row is read or any column type is checked, and the first unlisted column, in the file’s column order, is refused.
Fields:
| Field | Description |
|---|---|
path | The Parquet file |
field | The unlisted column name |
message | One of the three forms below |
The message takes the first form that applies:
column "<name>" is no longer read; <instruction>for a column with an instruction of its own:residual_std_ratioinscenarios/inflow_ar_coefficients.parquet,reference_volume_hm3insystem/hydro_energy_productivity.parquetanddateinscenarios/inflow_history.parquet;unknown column "<name>"; did you mean "<column>"?when a column the file may carry is within an edit distance of a third of the longer name (at least 1), ignoring case; the nearest one is named;unknown column "<name>"; the columns this file may carry are <columns>otherwise, listing every column the file may carry.
Examples:
A misspelled column, mean_m3 for mean_m3s, in scenarios/inflow_seasonal_stats.parquet:
[SchemaViolation] scenarios/inflow_seasonal_stats.parquet: field mean_m3: unknown column "mean_m3"; did you mean "mean_m3s"?The same file with its hydro_id column named hydro, which is near no column the file may carry:
[SchemaViolation] scenarios/inflow_seasonal_stats.parquet: field hydro: unknown column "hydro"; the columns this file may carry are hydro_id, stage_id, mean_m3s, std_m3sA residual_std_ratio column in scenarios/inflow_ar_coefficients.parquet:
[SchemaViolation] scenarios/inflow_ar_coefficients.parquet: field residual_std_ratio: column "residual_std_ratio" is no longer read; it is derived from the AR coefficients at load; remove the columnA DataFrame that pandas DataFrame.to_parquet wrote after its rows were reordered, which keeps the index as a column:
[SchemaViolation] scenarios/inflow_seasonal_stats.parquet: field __index_level_0__: unknown column "__index_level_0__"; the columns this file may carry are hydro_id, stage_id, mean_m3s, std_m3sResolution: Rename the column as the hint says, or remove it; for a column
with an instruction of its own, follow the instruction. pandas
DataFrame.to_parquet writes an index other than the default range index (the
index a filtered or reordered DataFrame keeps) as a column named
__index_level_0__: pass index=False, or build the table with
pa.Table.from_pandas(df, schema=schema).
Missing required Parquet column
Seção intitulada “Missing required Parquet column”When it occurs: A Parquet input without a required column is a schema failure naming the required column. A file that carries the column under another name is refused first, for that name (Unknown Parquet column).
Fields:
| Field | Description |
|---|---|
path | The Parquet file |
field | The required column name |
message | missing required column "<name>" |
Example: A scenarios/inflow_seasonal_stats.parquet without its hydro_id column:
[SchemaViolation] scenarios/inflow_seasonal_stats.parquet: field hydro_id: missing required column "hydro_id"Resolution: Add the column under the name the file requires. The column tables of Case Format list the required columns of every file.
Scenario-source admission rules
Seção intitulada “Scenario-source admission rules”When it occurs: A training.scenario_source or simulation.scenario_source
block of config.json breaks an admission rule. The rules are checked when
config.json loads, so novomodelo validate and novomodelo run both exit 1. In the
table, {section} stands for training or simulation, whichever block broke
the rule, and {from} and {to} stand for the first and last year of the range
as the case declares them. The printed message shows those values in place of
the placeholders.
| Rule | Field | Message |
|---|---|---|
openings under simulation | simulation.scenario_source.openings | openings is only valid under training.scenario_source, not simulation.scenario_source |
historical_years without a historical class | {section}.scenario_source.historical_years | historical_years is specified but no class uses the 'historical' scheme |
historical on load or ncs | {section}.scenario_source.load.scheme or {section}.scenario_source.ncs.scheme | historical scheme is only valid for the inflow class |
Missing seed | {section}.scenario_source.seed | seed is required when any class uses out_of_sample or external scheme |
Inverted historical_years range | {section}.scenario_source.historical_years | range 'from' ({from}) must be <= 'to' ({to}) |
Example: novomodelo validate on a case whose training.scenario_source sets the
inflow class to out_of_sample and no seed:
[SchemaViolation] config.json: field training.scenario_source.seed: seed is required when any class uses out_of_sample or external schemenovomodelo validate prints this line after an error: prefix. novomodelo run prints
it after error: constraint violation: .
Resolution: Configuration lists the
scenario_source keys. Find the message in the table above, then fix that rule:
openings: declare it undertraining.scenario_sourceonly.historical_years: remove it, or set the inflow class to thehistoricalscheme.loadorncs: use another scheme; only the inflow class takeshistorical.seed: add it to the block.- Inverted
historical_yearsrange: setfromno later thanto.
A declared opening-tree file that is missing is reported in the stochastic phase: Opening-tree file missing.
Inverted estimation.history_years range
Seção intitulada “Inverted estimation.history_years range”When it occurs: config.json’s estimation.history_years range has a
from year after its to year. The range is checked when config.json
loads, so novomodelo validate and novomodelo run both exit 1, whether or
not the run estimates from the inflow history.
[SchemaViolation] config.json: field estimation.history_years: range 'from' ({from}) must be <= 'to' ({to})Resolution: Set from no later than to; see
Configuration — estimation.
Invalid anticipated-thermal lead
Seção intitulada “Invalid anticipated-thermal lead”When it occurs: A thermal’s anticipated_config in system/thermals.json
takes exactly one of two keys: lead_stages (an integer of at least 1) or
lead_time_hours (a finite number above 0). A lead longer than the whole study
horizon must also reach a declared post-study stage. Four failures each add one
line to the validation report:
lead_stagesis 0.lead_time_hoursis zero or negative.- The object matches neither accepted shape, for example because it has both keys, has neither key, or has a negative
lead_stages. - The lead is longer than the whole study horizon and reaches no declared post-study stage.
Messages: novomodelo validate prints one error: line for each failure. The first
three failures stop system/thermals.json at its first offending entry, so a file
with several bad leads reports only the first; the horizon rule reports every
offending thermal. The captures follow the order of the list above.
error: [SchemaViolation] system/thermals.json: field thermals[0].anticipated_config.lead_stages: lead_stages must be >= 1, got 0error: [SchemaViolation] system/thermals.json: field thermals[0].anticipated_config.lead_time_hours: lead_time_hours must be finite and > 0.0, got -1error: [ParseError] system/thermals.json: parse error: data did not match any variant of untagged enum RawAnticipatedConfig at line 18 column 5error: [BusinessRuleViolation] system/thermals.json (thermals[id=0].anticipated_config.lead_stages): Thermal 0: lead_stages exceeds study horizon (lead_stages=9, n_stages=4); the plant can never deliver within the study horizonA lead_time_hours lead that fails the horizon rule produces this message
instead of the lead_stages one above:
Thermal {thermal_id}: lead_time exceeds study horizon (lead_time={delta_hours}, total_horizon_hours={total_horizon_hours}); the plant can never deliver within the study horizon{thermal_id} is the thermal’s id, {delta_hours} is its lead in hours, and
{total_horizon_hours} is the length of the whole study horizon in hours. In
the SchemaViolation lines, the index in thermals[0] is the entry’s position in the thermals array, counting from 0; the horizon message names the thermal id
instead, as in thermals[id=0].
Resolution: Keep one of the two keys: give lead_stages an integer of at
least 1, or lead_time_hours a number above 0. For a lead longer than the study
horizon, shorten the lead, or declare, in post_study_stages.json, a post-study stage that the lead
reaches. See
System Element Modeling Overview §4 for the
anticipated-thermal model and
system/thermals.json
for the file’s fields.
Spillage-band inversion
Seção intitulada “Spillage-band inversion”When it occurs: An inverted spillage band (min_spillage_m3s > max_spillage_m3s)
or a negative min_diversion_m3s, min_spillage_m3s, or max_spillage_m3s in
constraints/hydro_bounds.parquet is reported here (tagged [SchemaViolation])
when a full case is loaded, and surfaces as a standalone SchemaError when that
file is checked on its own.
Fields:
| Field | Description |
|---|---|
description | Contains a [SchemaViolation] constraints/hydro_bounds.parquet: field hydro_bounds[<i>].<column>: <message> line — see below |
Example:
[SchemaViolation] constraints/hydro_bounds.parquet: field hydro_bounds[0].max_spillage_m3s: max_spillage_m3s (5) must be >= min_spillage_m3s (10)[SchemaViolation] constraints/hydro_bounds.parquet: field hydro_bounds[0].min_diversion_m3s: value must be >= 0.0, got -5Resolution: Correct the offending row so min_spillage_m3s <= max_spillage_m3s, and so min_diversion_m3s, min_spillage_m3s, and
max_spillage_m3s are all non-negative. See
Case Format for
hydro_bounds.parquet’s column reference.
Negative diversion channel capacity
Seção intitulada “Negative diversion channel capacity”When it occurs: A hydro’s diversion.max_flow_m3s in system/hydros.json
is negative. The channel capacity bounds the diverted flow from above, and the
flow is bounded below by 0, so a negative capacity is rejected at load. A
channel without a capacity limit leaves max_flow_m3s out or sets it to
null.
Fields:
| Field | Description |
|---|---|
description | Contains a [SchemaViolation] system/hydros.json: field hydros[<i>].diversion.max_flow_m3s: max_flow_m3s must be >= 0, got <value> line, where <i> is the hydro’s zero-based position in the file |
Example:
[SchemaViolation] system/hydros.json: field hydros[0].diversion.max_flow_m3s: max_flow_m3s must be >= 0, got -5Resolution: Set max_flow_m3s to the channel’s capacity, 0 or more, or
leave it out for a channel without a capacity limit. A per-stage or per-block
max_diversion_m3s in constraints/hydro_bounds.parquet still caps the flow.
InvalidReference
Seção intitulada “InvalidReference”Severity: Error
When it occurs: A cross-entity foreign-key reference points to an entity
that does not exist in the expected registry. For example, one of a hydro
plant’s unit groups’ bus_id references a bus that is not in
system/buses.json. Emitted when the cross-entity references are resolved.
Example:
[InvalidReference] system/hydros.json (Hydro 0 unit group 0): Hydro 0 unit group 0 references non-existent Bus 99 via field 'bus_id'Resolution: Either add the referenced entity to its registry file, or
correct the ID in the referencing file. Check all ID references:
unit_groups[].bus_id, thermals.bus_id, lines.source_bus_id,
lines.target_bus_id, hydros.downstream_id.
See also: a constraints/ncs_bounds.parquet row with an undeclared stage_id is reported under this
kind — see
Undeclared stage_id in bound-override parquet.
Generic-constraint bound reference with no activation rows
Seção intitulada “Generic-constraint bound reference with no activation rows”When it occurs: constraints/generic_constraint_bounds.parquet is the
activation grid for generic constraints — a constraint applies at
(stage, block) if and only if a row exists for it there, independent of
whether the row supplies a numeric endpoint or the endpoint comes entirely
from the constraint’s own inline affine remainder (an inline <= @demanda,
say). A constraint whose only endpoints come from that affine remainder, but
which has zero rows in the bounds parquet, is collected as InvalidReference
— the reference would otherwise apply to nothing and be silently inert.
Fields:
| Field | Description |
|---|---|
description | Contains a [InvalidReference] constraints/generic_constraints.json (GenericConstraint <id>): GenericConstraint <id> declares a bound reference but has no activation rows in generic_constraint_bounds.parquet: the reference would apply to nothing line |
Example:
constraint violation: [InvalidReference] constraints/generic_constraints.json (GenericConstraint 3): GenericConstraint 3 declares a bound reference but has no activation rows in generic_constraint_bounds.parquet: the reference would apply to nothingResolution: Add at least one row for the constraint’s id to
generic_constraint_bounds.parquet at every (stage, block) where it should
apply — the row may leave both bound_lower/bound_upper null as long as the
constraint’s own affine remainder supplies the value; the row’s job is then
only to activate the cell. See
Generic Constraints — the activation grid
for the full model.
DuplicateId
Seção intitulada “DuplicateId”Severity: Error
When it occurs: An id or key is declared twice where it must be unique.
Three cases emit this kind: a unit-group id declared twice in one hydro plant
(unit-group ids are unique within a plant, not globally); a policy-graph node
id declared twice in policy_graph.nodes[] of stages.json; and two rows of a
constraints/*_bounds.parquet override file that set the same column for the
same entity, stage and block. An entity id declared twice in a registry file,
such as two buses with the same id in system/buses.json, is a
SchemaViolation, not a DuplicateId; see the
two-buses example there.
Example:
[DuplicateId] system/hydros.json (Hydro 0): Hydro 0: unit group id 0 is declared more than once; unit group ids must be unique within a plantResolution: Rename the repeated unit-group or node id, or remove or merge
the bound-override rows that set the same column twice.
InvalidValue
Seção intitulada “InvalidValue”Severity: Error
When it occurs: A value violates a domain rule that novomodelo validate
checks once the files have loaded. Examples: the outgoing transition
probabilities from a stage in stages.json do not sum to 1.0, or a study stage
has an empty blocks array. A reservoir whose min_storage_hm3 exceeds
max_storage_hm3, and a stage whose num_openings is 0, are reported as
SchemaViolation lines instead.
Example:
[InvalidValue] stages.json: outgoing transition probabilities from stage 0 sum to 0.50000000 (expected 1.0 ±0.000001); probability must sum to 1.0[InvalidValue] stages.json: stage 1 declares no blocks; every study stage must declare at least one blockResolution: Correct the value named in the message. Consult
the Case Format page for documented constraints. For transitions,
make the outgoing probabilities from each stage sum to 1.0. For stages, declare at least one
block in every study stage’s blocks array.
See also: a positive min_diversion_m3s or max_diversion_m3s on a hydro
with no declared diversion channel is reported under this kind — see
Diversion bound without a declared channel.
A constraints/hydro_bounds.parquet storage bound outside the reservoir’s range,
or a study stage whose minimum storage exceeds its maximum, is reported under
this kind too — see
Stage storage bounds refused at load.
An initial storage outside the hydro’s storage range, or listed in the wrong
initial_conditions.json array, is reported under this kind too — see
Initial storage refused at load.
Generic-constraint bounds row with neither endpoint and no affine remainder
Seção intitulada “Generic-constraint bounds row with neither endpoint and no affine remainder”When it occurs: A generic_constraint_bounds.parquet row with
bound_lower = null and bound_upper = null is legal only when the
constraint’s own bound_lower_affine/bound_upper_affine supplies at least
one endpoint (the row then only activates the cell, per above). A both-null
row on a constraint with no affine remainder on either side has no
endpoint at all and is collected as InvalidValue.
Fields:
| Field | Description |
|---|---|
description | Contains a [InvalidValue] constraints/generic_constraint_bounds.parquet (GenericConstraintBoundsRow[<i>]): GenericConstraintBoundsRow[<i>] on constraint <id> has neither bound_lower nor bound_upper: at least one endpoint is required line |
Example:
constraint violation: [InvalidValue] constraints/generic_constraint_bounds.parquet (GenericConstraintBoundsRow[4]): GenericConstraintBoundsRow[4] on constraint 3 has neither bound_lower nor bound_upper: at least one endpoint is requiredResolution: Either supply bound_lower and/or bound_upper on the row,
or add an inline relational operator (<=, >=, ==) to the constraint’s
expression so an affine remainder fills the missing endpoint. See
Generic Constraints — the activation grid.
Diversion bound without a declared channel
Seção intitulada “Diversion bound without a declared channel”When it occurs: constraints/hydro_bounds.parquet may override a hydro’s
min_diversion_m3s and max_diversion_m3s per (hydro, stage) or per block.
When the hydro declares no diversion channel, its diversion flow is fixed at
[0, 0]. A positive floor would be the infeasible interval [min > 0, 0], and
a positive ceiling would divert water that no plant receives. The business-rule
check rejects either override before it reaches the LP, with one finding per
field.
Fields:
| Field | Description |
|---|---|
description | Contains a [InvalidValue] constraints/hydro_bounds.parquet (Hydro <id>): Hydro <id>: hydro_bounds row at stage_id=<stage>[ block_id=<block>] sets <field>=<value>, but the hydro declares no diversion channel; without a channel the diversion column is [0, 0] line, where <field> is min_diversion_m3s or max_diversion_m3s |
Example:
[InvalidValue] constraints/hydro_bounds.parquet (Hydro 0): Hydro 0: hydro_bounds row at stage_id=1 sets max_diversion_m3s=25, but the hydro declares no diversion channel; without a channel the diversion column is [0, 0]Resolution: Either declare a diversion channel on the hydro in
system/hydros.json (see System Element Modeling Overview), or remove
the positive min_diversion_m3s or max_diversion_m3s override for that
(hydro, stage) in constraints/hydro_bounds.parquet.
Stage storage bounds refused at load
Seção intitulada “Stage storage bounds refused at load”When it occurs: constraints/hydro_bounds.parquet sets a storage bound
outside the reservoir’s range, or leaves a study stage whose minimum storage
exceeds its maximum:
- A row’s
max_storage_hm3lies above the reservoir’smax_storage_hm3insystem/hydros.json, or itsmin_storage_hm3lies below the reservoir’smin_storage_hm3(the dead volume), beyond a relative tolerance of1e-9(an absolute one below 1 hm³). Each column out of range is one finding, so a row out of range on both sides gives two. A row on ahydro_idthe case does not declare is reported asInvalidReferenceinstead. - On a study stage, the storage minimum in force exceeds the maximum in force.
Each bound in force is the value on the stage’s row, else the reservoir’s
own, so two rows can set the minimum and the maximum separately, and one
override can cross the reservoir’s opposite bound. Equal bounds are accepted.
One finding lists every (hydro, stage) pair. A reservoir whose own
min_storage_hm3exceeds itsmax_storage_hm3is refused first, as aSchemaViolationofsystem/hydros.json.
The geometry, production and evaporation models of a hydro cover only its reservoir’s range, so a stage’s storage bounds must lie within it.
Fields:
| Field | Description |
|---|---|
description | Contains a [InvalidValue] constraints/hydro_bounds.parquet (hydro_id=<id>, stage_id=<stage>): Hydro <id>: hydro_bounds row at stage_id=<stage>[, block_id=<block>] sets <column>=<value>, above the reservoir's <column> (<declared>) in system/hydros.json; a stage's storage bounds must lie within the reservoir's range line, with below in place of above for min_storage_hm3, or a [InvalidValue] constraints/hydro_bounds.parquet: min_storage_hm3 exceeds max_storage_hm3 at <n> (hydro, stage) pair(s), so no storage satisfies those stages: <pairs> line |
Each pair is written Hydro <id> at stage <stage> (<min> > <max>), with the
pairs sorted by hydro id, then stage id, and joined with , .
Examples:
[InvalidValue] constraints/hydro_bounds.parquet (hydro_id=0, stage_id=1): Hydro 0: hydro_bounds row at stage_id=1 sets max_storage_hm3=1200, above the reservoir's max_storage_hm3 (1000) in system/hydros.json; a stage's storage bounds must lie within the reservoir's range[InvalidValue] constraints/hydro_bounds.parquet (hydro_id=0, stage_id=1): Hydro 0: hydro_bounds row at stage_id=1 sets min_storage_hm3=50, below the reservoir's min_storage_hm3 (100) in system/hydros.json; a stage's storage bounds must lie within the reservoir's rangeIn the next case, stage 1 takes its minimum and its maximum from two rows, and stage 2’s maximum falls below the reservoir’s minimum of 100 hm³, which is that stage’s minimum in force:
[InvalidValue] constraints/hydro_bounds.parquet: min_storage_hm3 exceeds max_storage_hm3 at 2 (hydro, stage) pair(s), so no storage satisfies those stages: Hydro 0 at stage 1 (600 > 400), Hydro 0 at stage 2 (100 > 50)Resolution: Keep each stage’s min_storage_hm3 and max_storage_hm3 within
the reservoir’s min_storage_hm3 to max_storage_hm3 in system/hydros.json,
or correct the reservoir’s range when it is the value in error. On each listed
stage, lower the minimum or raise the maximum in force. See
constraints/hydro_bounds.parquet.
Initial storage refused at load
Seção intitulada “Initial storage refused at load”When it occurs: initial_conditions.json seeds a hydro’s storage outside
its range or in the array that does not match its filling configuration:
- A
storage[].value_hm3of a hydro without afillingconfiguration lies outside that hydro’s own[min_storage_hm3, max_storage_hm3]fromsystem/hydros.json, beyond a relative tolerance of1e-9(an absolute one below 1 hm³). A hydro that enters service after the first stage is checked too. The value is refused, never clamped. A hydro whosemin_storage_hm3exceeds itsmax_storage_hm3reports thatSchemaViolationinstead. - A hydro with a
fillingconfiguration is listed understorage, or a hydro without one is listed underfilling_storage.
The stage min_storage_hm3 and max_storage_hm3 of
constraints/hydro_bounds.parquet bound the end of their stage, not the initial
storage; a seed outside the bounds of the hydro’s first operating stage is the
ModelQuality warning, not an error.
Fields:
| Field | Description |
|---|---|
description | Contains a [InvalidValue] initial_conditions.json (Hydro <id>): Hydro <id>: initial storage (<value>) must lie in [min_storage_hm3, max_storage_hm3] = [<min>, <max>] line for a value out of range, or Hydro <id>: has a filling configuration, so its initial storage belongs in filling_storage, not storage or Hydro <id>: has no filling configuration, so its initial storage belongs in storage, not filling_storage for the wrong array |
Example:
[InvalidValue] initial_conditions.json (Hydro 0): Hydro 0: initial storage (1200) must lie in [min_storage_hm3, max_storage_hm3] = [0, 1000]Resolution: Set the value inside the hydro’s [min_storage_hm3, max_storage_hm3], or move the entry to filling_storage for a hydro with a
filling configuration and to storage for one without. See
Initial Conditions.
CycleDetected
Seção intitulada “CycleDetected”Severity: Error
When it occurs: A directed graph that must be acyclic contains a cycle.
Two graphs are checked. The hydro cascade: the downstream_id links among hydro
plants must form a directed forest (no cycles), so a cycle would mean plant A
drains into plant B which drains back into plant A. The policy graph: the
policy_graph.nodes[] of stages.json, linked by transitions[], must be
acyclic; this check applies only when nodes[] is declared.
Messages:
[CycleDetected] system/hydros.json: hydro cascade contains a cycle involving hydro IDs: [0, 1]The policy-graph nodes message:
policy-graph nodes contain a cycle; the node graph must be acyclicnovomodelo validate prints it as [CycleDetected] stages.json: <message>, where
<message> is the text above.
Resolution: Review the downstream_id chain for the listed plants and remove
the cycle. Every hydro cascade must be a directed tree rooted at plants with no
downstream (tailwater discharge). For the policy graph, remove the
transitions[] entry that closes the cycle.
DimensionMismatch
Seção intitulada “DimensionMismatch”Severity: Error
When it occurs: A cross-file coverage check fails. For example, when
scenarios/inflow_seasonal_stats.parquet is present, every hydro needs a row
for each study stage in which it is active, and each missing (hydro, stage)
pair is one error that names the hydro and the stage. A mismatch means an
optional per-entity file provides data for some entities but not all that
require it. When system/fpha_hyperplanes.parquet holds any row, every plant
configured with the fpha model that has turbine capacity needs rows of its
own, whatever its source, and one without them is reported as
Hydro <id> is configured with FPHA model but has no FPHA hyperplanes.
Example:
[DimensionMismatch] scenarios/inflow_seasonal_stats.parquet (Hydro 1): Hydro 1 missing inflow seasonal stats for stage 0Resolution: Add the missing rows to the Parquet file; the message names the hydro and the stage that lack one. When that file is present, every hydro needs a row for each study stage in which it is active.
BusinessRuleViolation
Seção intitulada “BusinessRuleViolation”Severity: Error
When it occurs: A domain-specific business rule is violated that cannot
be expressed as a simple range constraint. Examples: a negative turbined_cost
on a hydro whose generation model is fpha, a filling schedule that cannot
reach the dead volume before the hydro enters operation, the anticipated-thermal
and post-study-boundary rules, a bound-override row that names an undeclared
stage_id, a pumping station in service at a stage where its source or destination hydro is not Operating, a computed-FPHA hydro whose system/hydro_geometry.parquet volumes do not cover its storage range, a per-block generic-constraint reference that the stage’s blocks
cannot satisfy, or a stage that shares a season_id with stages of another duration and is neither the season’s whole period nor a slice of it (stages.json). One check reports a BusinessRuleViolation as a warning: when the inflow model is estimated from scenarios/inflow_history.parquet and a hydro has more than one observation in one season of a year, novomodelo validate prints a warning: line (exit 0) saying the observations are aggregated to season resolution.
Example:
error: [BusinessRuleViolation] penalties.json (Hydro 0): Hydro 0: turbined_cost (-0.05) must be non-negative (>= 0) for FPHA hydros; negative values distort LP dispatchResolution: Read the message carefully — it describes the specific rule that was violated and which entities are involved. For the two penalty rules, see Load-time penalty checks.
See also: the entries below hold the anticipated-thermal and post-study boundary rules
(Commitment on a non-anticipated thermal,
Missing commitment window on an anticipated thermal,
Post-study boundary unanchored or malformed and
Uncovered or over-covered past_anticipated_commitments window),
the undeclared-stage_id bound-override rule
(Undeclared stage_id in bound-override parquet) and
the per-block generic-constraint references
(Per-block generic-constraint references).
The pumping-station rule is under
Pumping station outside its endpoints’ Operating windows.
The computed-FPHA geometry rule is under
Computed-FPHA geometry short of the storage range.
The estimation-window rule is under
Estimation history years outside the history.
The horizon rule of Invalid anticipated-thermal lead also prints a
[BusinessRuleViolation] line; that entry sits under SchemaViolation, where two of its four lines print.
The stage-volume rules of generic constraints are under
Stage-volume generic constraints.
Deterministic external inflow column under an autoregressive model
Seção intitulada “Deterministic external inflow column under an autoregressive model”When it occurs: Under the external inflow sampling scheme, an inflow’s
seasonal mean and standard deviation are replaced by the sample moments of its
external scenario file only for a hydro of autoregressive order 0 with no annual
component; a hydro whose files declare a lag coefficient or an annual component
keeps the statistics its own files declare. The substitution is per class: a
load or non-controllable-source class takes its moments from its external file
only when that class is itself external.
A constant (σ = 0) column is accepted for load, NCS, and a hydro of order 0 with no annual component, but rejected for a hydro whose files declare an autoregressive order above 0 or an annual component: a single deterministic value cannot stand in for such a model, since it would have to equal that model’s own stage-by-stage deterministic PAR output, which the loader does not reconstruct from a flat column.
Fields:
| Field | Description |
|---|---|
description | Contains a [BusinessRuleViolation] <external inflow file> (inflow entity <e> stage <stage_id>): <message> line |
Example:
constraint violation: [BusinessRuleViolation] scenarios/external_inflow_scenarios.parquet (inflow entity 7 stage 3): inflow external library at stage 3, entity 7: every scenario value is constant (σ = 0), but this hydro's inflow follows an autoregressive model of order > 0; a deterministic value here would have to equal that model's own deterministic PAR output at every stage, which this loader does not compute upstreamResolution: Give the external column genuine stage-to-stage variation, or
drop the plant’s autoregressive inflow model to order 0 (no lag coefficient, no
annual component) if its inflow really is deterministic. See
Scenario Generation §4.4 for the accept/reject
rule and scenario_source for the
scheme configuration.
Scalar parameters outside the constraints directory
Seção intitulada “Scalar parameters outside the constraints directory”When it occurs: Scalar parameters are read from
constraints/generic_parameters.json only, beside the generic constraints that
reference its @name parameters. A file at system/scalar_parameters.json is
rejected whatever its content; the loader never reads it, so a well-formed file at that path is still refused.
Fields:
| Field | Description |
|---|---|
description | Contains a [BusinessRuleViolation] system/scalar_parameters.json: system/scalar_parameters.json is no longer read; scalar parameters are now read from constraints/generic_parameters.json, beside the constraints that reference them by @name. Move the file (its contents are unchanged). line |
Example:
[BusinessRuleViolation] system/scalar_parameters.json: system/scalar_parameters.json is no longer read; scalar parameters are now read from constraints/generic_parameters.json, beside the constraints that reference them by @name. Move the file (its contents are unchanged).Resolution: mkdir -p <case>/constraints && git mv <case>/system/scalar_parameters.json <case>/constraints/generic_parameters.json — the contents do not change. See
Generic Constraints — the parameter kinds
for the current file’s schema.
Commitment on a non-anticipated thermal
Seção intitulada “Commitment on a non-anticipated thermal”When it occurs: initial_conditions.json’s past_anticipated_commitments
entries declare an externally-decided commitment for an anticipated thermal,
keyed by thermal_id. Case validation rejects any entry whose thermal_id
names no thermal with an anticipated_config — either the thermal does not
exist, or it exists but is not configured as anticipated.
Fields:
| Field | Description |
|---|---|
description | Contains a [BusinessRuleViolation] initial_conditions.json (initial_conditions.past_anticipated_commitments[thermal_id=<id>]): Thermal <id>: referenced in past_anticipated_commitments but is not an anticipated thermal (anticipated_config is None or thermal does not exist) line |
Example:
constraint violation: [BusinessRuleViolation] initial_conditions.json (initial_conditions.past_anticipated_commitments[thermal_id=12]): Thermal 12: referenced in past_anticipated_commitments but is not an anticipated thermal (anticipated_config is None or thermal does not exist)Resolution: Either set anticipated_config on thermal <id> in
system/thermals.json, or remove/correct the thermal_id in the offending
past_anticipated_commitments entry. See
System Element Modeling Overview §4 for anticipated-thermal configuration and Case Format
for initial_conditions.json’s schema.
Missing commitment window on an anticipated thermal
Seção intitulada “Missing commitment window on an anticipated thermal”When it occurs: Every thermal with an anticipated_config needs at least one
window in initial_conditions.json’s past_anticipated_commitments, keyed by
thermal_id. Case validation rejects a thermal that has none, for a lead given in
stages and for a lead given in hours alike.
Fields:
| Field | Description |
|---|---|
description | Contains a [BusinessRuleViolation] initial_conditions.json (initial_conditions.past_anticipated_commitments): Thermal <id>: missing entry in initial_conditions.past_anticipated_commitments; every anticipated thermal must have at least one commitment window line |
Example:
[BusinessRuleViolation] initial_conditions.json (initial_conditions.past_anticipated_commitments): Thermal 0: missing entry in initial_conditions.past_anticipated_commitments; every anticipated thermal must have at least one commitment windowResolution: Add a window for the thermal to past_anticipated_commitments (a
committed 0 MW is an explicit window), or remove the thermal’s anticipated_config.
See Uncovered or over-covered past_anticipated_commitments window
for the coverage the windows must reach and Case Format
for initial_conditions.json’s schema.
Post-study boundary unanchored or malformed
Seção intitulada “Post-study boundary unanchored or malformed”When it occurs: The business-rule check validates post_study_stages.json — the
post-horizon boundary calendar — and the anticipated-thermal deliveries that
resolve onto it. Several distinct failures are collected under this one check.
(A plant whose lead is longer than the whole study horizon and reaches no
declared post-study stage is caught earlier, at anticipated-thermal validation,
with a
system/thermals.json … the plant can never deliver within the study horizon
message (see
Invalid anticipated-thermal lead); to clear
it, shorten the lead or declare a post-study stage the lead reaches — see
System Element Modeling Overview §4.)
The post-study failures, keyed to post_study_stages.json:
- The post-study calendar’s first stage does not start exactly at the study horizon end.
- The post-study stages are not date-contiguous (a gap or overlap between consecutive stages).
- A post-study stage’s
duration_hoursrounds to a non-positive whole-day span. - Rule 1 — a plant’s lead reaches a post-study stage with no
thermal_boundscell for its(thermal_id, post_study_stage_index). - V2 — a plant’s commitments decided before the study and delivered past the
horizon do not tile the post-study stages they cover at coverage
1.0. - V3 — a commitment window covers a post-study stage the study itself
decides (
carried), or one past the plant’s decision reach. - V5 — a non-zero fixed commitment covers a post-study stage outside the plant’s commissioning window.
Fields:
| Field | Description |
|---|---|
description | Contains one [BusinessRuleViolation] post_study_stages.json (...): <message> line per failure — see the messages below |
Example:
constraint violation: [BusinessRuleViolation] post_study_stages.json (stages[0].start_date): first post-study stage starts 2026-09-08 but the study horizon ends 2026-09-05; the post-study calendar must begin exactly at the study horizon end.constraint violation: [BusinessRuleViolation] post_study_stages.json (stages start_date=2026-10-01): post-study stages are not date-contiguous: the stage starting 2026-09-05 ends 2026-09-28 but the next stage starts 2026-10-01; each stage must end exactly where the next begins.constraint violation: [BusinessRuleViolation] post_study_stages.json (thermals[id=12].anticipated_config): Thermal 12: anticipated lead reaches post-study stage index 0, but post_study_stages.json has no thermal_bounds entry for (thermal_id 12, post_study_stage_index 0).constraint violation: [BusinessRuleViolation] post_study_stages.json (thermals[id=12].anticipated_config): Thermal 12: past_anticipated_commitments do not tile post-study stage index(es) [0] at coverage 1.0; declare the fixed commitment for each (a committed 0 MW is explicit).constraint violation: [BusinessRuleViolation] post_study_stages.json (thermals[id=12].anticipated_config): Thermal 12: past_anticipated_commitments cover post-study stage index(es) [1], which the study itself decides; a declared fixed value there contradicts the study's own decision. Remove the window, or lengthen anticipated_config's lead so the delivery becomes pre-study-decided.constraint violation: [BusinessRuleViolation] post_study_stages.json (thermals[id=12].anticipated_config): Thermal 12: past_anticipated_commitments cover post-study stage index(es) [2], which are past the plant's decision reach and cannot be represented. Remove the window, or shorten anticipated_config's lead so the delivery falls inside the reach.constraint violation: [BusinessRuleViolation] post_study_stages.json (thermals[id=12].anticipated_config): Thermal 12: past_anticipated_commitments window [2026-10-01, 2026-11-01) value_mw = 120 covers post-study stage index 0, which is outside the plant's commissioning window [entry=Some(0), exit=Some(6)); the plant is not in service for this stage and the fixed commitment cannot be delivered. Declare a zero commitment at this stage, or widen the commissioning window.Resolution: Declare post_study_stages.json with its first stage starting
exactly at the study horizon end and every stage date-contiguous with the next.
Add a thermal_bounds cell for every (thermal_id, post_study_stage_index) a
plant’s in-study-decided lead reaches. Tile every post-study stage that a
past_anticipated_commitments window for a commitment decided before the study
covers, at coverage 1.0, never covering a stage the study decides or one past the plant’s reach,
and keep a non-zero fixed commitment inside the plant’s commissioning window.
See Post-Study Boundary & Chained Studies for the boundary model and
Case Format for
post_study_stages.json’s schema.
Uncovered or over-covered past_anticipated_commitments window
Seção intitulada “Uncovered or over-covered past_anticipated_commitments window”When it occurs: An anticipated thermal’s past_anticipated_commitments
windows must tile exactly the in-study delivery stages the plant decided
before the study — every such stage covered at fraction 1.0 — and never a
stage the study itself decides. The business-rule check reports a gap (an
uncovered leading stage), an over-reach (a window covering a study-decided
stage), and a horizon-straddle (a single window crossing the horizon end) as
separate diagnostics; each can fire independently. A window may legitimately
extend past the horizon (a commitment decided before the study and delivered
past the horizon; for the equivalent term in other planning tools, see the
Glossary) — that post-study coverage is validated
separately, under
Post-study boundary above.
Fields:
| Field | Description |
|---|---|
description | Contains a [BusinessRuleViolation] initial_conditions.json (thermals[id=<id>].anticipated_config): <message> line — see the messages below |
Example:
constraint violation: [BusinessRuleViolation] initial_conditions.json (thermals[id=7].anticipated_config): Thermal 7: past_anticipated_commitments do not tile the leading 2 delivery stage(s) at coverage 1.0; study stage id(s) [0] are not covered exactly once. Write a commitment window (a committed 0 MW is explicit) for every leading delivery stage.constraint violation: [BusinessRuleViolation] initial_conditions.json (thermals[id=7].anticipated_config): Thermal 7: past_anticipated_commitments cover study stage id(s) [3] beyond the leading 2 calendar-derived delivery stage(s); a commitment window may not cover a study stage the study itself decides. Shorten the plant's anticipated_config lead so its window stays within the leading 2 delivery stage(s).constraint violation: [BusinessRuleViolation] initial_conditions.json (thermals[id=7].anticipated_config): Thermal 7: past_anticipated_commitments window [2026-08-15, 2026-09-15) straddles the study horizon end (2026-09-01); a single window may not cover both in-study and post-study delivery. Declare two windows split at the horizon instead: one ending at 2026-09-01 for the in-study coverage, one starting at 2026-09-01 for the post-study coverage.Resolution: Write a commitment window for every in-study delivery stage the
plant decided before the study (a committed 0 MW is a legitimate, explicit
window — not an omission), never covering a stage the study itself decides (end the window earlier, or
lengthen the plant’s anticipated_config lead if that stage is in fact decided
before the study), and split any window at the horizon end rather than
straddling it. Those are the in-study delivery stages whose decision falls
before the first study stage: the first lead_stages stages, or, for
lead_time_hours, every stage whose decision instant — one lead before the
stage’s end — is at or before the study start. See
System Element Modeling Overview §4.
Undeclared stage_id in bound-override parquet
Seção intitulada “Undeclared stage_id in bound-override parquet”When it occurs: A row in constraints/{thermal,hydro,line,pumping,contract,hydro_unit_group}_bounds.parquet
whose stage_id is not a declared study stage (membership in the declared ids of
stages.json, which may be gapped or start at 1) is rejected at novomodelo validate
as BusinessRuleViolation; a constraints/ncs_bounds.parquet
row is rejected as InvalidReference with
NcsBoundsRow[i] has invalid stage_id N (not a valid study stage). Rows in
constraints/generic_constraint_bounds.parquet and
constraints/penalty_overrides_*.parquet with an undeclared stage_id are
not rejected and have no effect.
Fields:
| Field | Description |
|---|---|
description | One [BusinessRuleViolation] constraints/{family}_bounds.parquet (...): ... line per rejected row for the six families, or one [InvalidReference] constraints/ncs_bounds.parquet: NcsBoundsRow[i] has invalid stage_id N ... line for NCS |
Example:
error: [BusinessRuleViolation] constraints/hydro_bounds.parquet (hydro_id=0, stage_id=15): Hydro 0: hydro_bounds override names stage_id=15, which is not a declared study stageResolution: Correct the stage_id value to match one of the declared stage
IDs in stages.json. For a typo (e.g., 15 instead of 5), fix the row; for a
stale override referencing a removed stage, delete the row or update the stages
declaration.
Per-block generic-constraint references
Seção intitulada “Per-block generic-constraint references”When it occurs: A generic-constraint term names a block that its stage
cannot expose. The check runs only for a (constraint, stage) pair that has a row
in constraints/generic_constraint_bounds.parquet. An evaporation reference is a
hydro_evaporation term; a storage reference is a hydro_storage_initial,
hydro_storage_final, hydro_useful_volume_initial, or
hydro_useful_volume_final term. With K the number of blocks the stage
declares, the check rejects four conditions:
- A block index of
Kor more in an evaporation or storage reference, on any stage. - An evaporation reference to a block from 1 to
K - 1on a parallel stage withK > 1. - An evaporation reference with no block on a chronological stage with
K > 1. - A storage reference to an interior block boundary, a boundary between two
blocks, on a parallel stage with
K > 1.
The rules are stated under
hydro_evaporation block references.
Kind, file, entity: BusinessRuleViolation,
constraints/generic_constraints.json, and the entity constraint[id=N], where
N is the constraint’s id.
Messages: novomodelo validate prints one error: line per rejection. The five
lines below show one message per template, in this order:
- An evaporation block of
Kor more. - An evaporation block from 1 to
K - 1on a parallel stage. - An interior storage boundary on a parallel stage.
- A storage block of
Kor more. - An evaporation reference with no block on a chronological stage.
error: [BusinessRuleViolation] constraints/generic_constraints.json (constraint[id=0]): Constraint "evap_out_of_range": per-block evaporation reference `hydro_evaporation(0, 5)` at stage 0 references block 5 which does not exist at stage 0 (K = 2)error: [BusinessRuleViolation] constraints/generic_constraints.json (constraint[id=1]): Constraint "evap_parallel_block": per-block evaporation reference `hydro_evaporation(0, 1)` at stage 0 names block 1, past the stage-level evaporation, which requires chronological block mode (stage 0 is parallel with 2 blocks); use block 0 or no blockerror: [BusinessRuleViolation] constraints/generic_constraints.json (constraint[id=2]): Constraint "storage_interior": per-block storage reference `hydro_storage_final(0, 0)` at stage 0 resolves to an interior boundary, which requires chronological block mode (stage 0 is parallel with 2 blocks)error: [BusinessRuleViolation] constraints/generic_constraints.json (constraint[id=3]): Constraint "storage_out_of_range": per-block storage reference `hydro_storage_initial(0, 5)` at stage 0 references block 5 which does not exist at stage 0 (K = 2)error: [BusinessRuleViolation] constraints/generic_constraints.json (constraint[id=4]): Constraint "evap_chronological_bare": stage-level `hydro_evaporation(0)` at chronological stage 1 is ambiguous — evaporation is per-block there (K = 2); name a block, e.g. `hydro_evaporation(0, 0)`Each per-block message quotes the whole term accessor(hydro, block); the stage-level
ambiguity message quotes accessor(hydro) and suggests a block term.
Resolution: Name a block that exists on the stage: block indices run from 0
to K - 1. On a parallel stage, address evaporation with block 0 or with no
block, and address a storage reference only at the stage’s start or end: block 0
or no block for an initial reference, the last block or no block for a final
reference. To address per-block quantities, set block_mode to "chronological"
on the stage in stages.json; a
chronological stage requires a named block for evaporation, as in
hydro_evaporation(<hydro>, 0).
Stage-volume generic constraints
Seção intitulada “Stage-volume generic constraints”When it occurs: A generic constraint with a hydro_outflow_volume,
hydro_diversion_volume or pumping_volume term is one stage-level row, so the
check refuses three things in it:
- a term that is not a stage volume,
hydro_storage, or ahydro_storage_initial,hydro_storage_final,hydro_useful_volume_initialorhydro_useful_volume_finalterm without a block argument, whether the expression writes it or a named expression brings it in; - a
per_stage_blockparameter that a coefficient or a bound reads, directly or throughexpressionparameters; - a row of the constraint in
constraints/generic_constraint_bounds.parquetwith ablock_id.
The rules are stated under Stage volumes.
Kind, file, entity: BusinessRuleViolation. A term or parameter refusal
reports constraints/generic_constraints.json and the entity constraint[id=N],
where N is the constraint’s id, whether or not the constraint has bounds
rows. A bounds-row refusal reports
constraints/generic_constraint_bounds.parquet and the entity
constraint_id=N, stage_id=S of the row.
Messages: novomodelo validate prints one error: line per refused term,
parameter and bounds row. A term that a named expression brings in is quoted
with (from @name) after it, naming each named expression whose own body
writes the term. The three lines below show one refusal of each kind, in the order above.
error: [BusinessRuleViolation] constraints/generic_constraints.json (constraint[id=1]): Constraint "release_vs_flow": `hydro_turbined(1)` cannot appear beside a stage-volume term; such a constraint takes only stage volumes, hydro_storage, and hydro_storage_* or hydro_useful_volume_* without a block argumenterror: [BusinessRuleViolation] constraints/generic_constraints.json (constraint[id=2]): Constraint "release_cap": parameter `@cap` is per_stage_block; a constraint with a stage-volume term takes no coefficient or bound that varies by blockerror: [BusinessRuleViolation] constraints/generic_constraint_bounds.parquet (constraint_id=3, stage_id=0): Constraint "diverted_cap": the bounds row at stage_id=0 has block_id=0; a constraint with a stage-volume term takes one row per stage with a null block_idResolution: Keep a stage-volume constraint to stage volumes and stage-level
storage: write a flow, generation or other per-block quantity as a constraint of
its own, or as its stage volume where one exists; replace a per_stage_block
parameter with a per_stage one; and set the block_id of each bounds row to
null.
Pumping station outside its endpoints’ Operating windows
Seção intitulada “Pumping station outside its endpoints’ Operating windows”When it occurs: A pumping station in system/pumping_stations.json is in service at a stage where its source or destination hydro is not Operating: before that hydro’s entry_stage_id, at or after its exit_stage_id, or while it is Filling. One line prints for each offending endpoint and names the earliest such stage.
PumpingStation {id}: active at stage {stage_id} while its {side} hydro {hid} is not Operating there (before entry_stage_id, at or after exit_stage_id, or Filling); a pumping station may operate only inside both endpoints' Operating windows{side} is source or destination. The line prints as [BusinessRuleViolation] system/pumping_stations.json (PumpingStation {id}): <message>.
Resolution: Keep the station in service only at stages where both hydros are Operating: adjust the entry_stage_id and exit_stage_id of the station, or those of the hydros.
Computed-FPHA geometry short of the storage range
Seção intitulada “Computed-FPHA geometry short of the storage range”When it occurs: A hydro whose production-model configuration has a source: "computed" entry has rows in system/hydro_geometry.parquet, and the volume range of those rows does not cover the hydro’s storage range, min_storage_hm3 to max_storage_hm3. The computed FPHA planes are fitted over that storage range. A hydro with no row in the file is left to the geometry-coverage rule of the validation table.
{entity}: the hydro_geometry.parquet volume range [{geometry_min}, {geometry_max}] hm³ does not cover its storage range [{min}, {max}] hm³, over which its computed FPHA planes are fitted; extend the geometry to cover it{entity} is Hydro {name} (id={id}). The line prints as [BusinessRuleViolation] system/hydro_geometry.parquet ({entity}): <message>.
Resolution: Extend the geometry in system/hydro_geometry.parquet to cover min_storage_hm3 to max_storage_hm3, or correct the storage range of the hydro.
Estimation history years outside the history
Seção intitulada “Estimation history years outside the history”When it occurs: The run estimates the inflow model from
scenarios/inflow_history.parquet (the case does not supply both
scenarios/inflow_seasonal_stats.parquet and
scenarios/inflow_ar_coefficients.parquet), and estimation.history_years
starts before the first year or ends after the last year of the file. The years
of the file are the start years of its rows, over every hydro. A case that
estimates nothing from the history is not checked.
estimation.history_years ({from} to {to}) reaches outside the years of scenarios/inflow_history.parquet ({first} to {last}); narrow the range to those yearsThe line prints as [BusinessRuleViolation] config.json: <message>.
Resolution: Narrow estimation.history_years to the years the file holds,
or extend the file; see
Configuration — estimation.
WarmStartIncompatible
Seção intitulada “WarmStartIncompatible”novomodelo validate reports a refused policy.mode = "warm_start" load of a run that trains as its phase, with the message labelled
<output dir>/<policy.path>: , and exits 1; a checkpoint the OS refuses to read reports IoError and exits 2.
The same kind carries the load’s warnings, which exit 0: Stored bases not used,
entity manifest absent (source slots: {n}, current slots: {m}); slot identity could not be verified, relying on state_dimension alone
and
slot {i} (entity_type={entity_type}, entity_id={entity_id}, subindex={subindex}) was dormant in the source policy but is active in the current study; loading its cut.
Policy-load errors gives the refusal messages.
ResumeIncompatible
Seção intitulada “ResumeIncompatible”novomodelo validate reports a refused policy.mode = "resume" load of a run that trains as its phase, with the message labelled
<output dir>/<policy.path>: , and exits 1; a checkpoint the OS refuses to read reports IoError and exits 2.
The same kind carries the load’s warnings, which exit 0: Stored bases not used,
entity manifest absent (source slots: {n}, current slots: {m}); slot identity could not be verified, relying on state_dimension alone
and
slot {i} (entity_type={entity_type}, entity_id={entity_id}, subindex={subindex}) was dormant in the source policy but is active in the current study; loading its cut.
Policy-load errors gives the refusal messages.
Stored bases not used
Seção intitulada “Stored bases not used”A full-FCF load uses a stored LP basis only when it fits its stage LP (Policy Management — Stored-basis gate states the rule); the others are left out with one warning, and the load proceeds:
warning: stored bases not used: {n} of {m} do not fit the current LP (first: node {node}, {reason}); a stored basis is used only when its column count equals the LP's, its row count equals the LP's template rows plus its recorded cut rows, its basic count equals its row count, and every recorded cut-row slot holds a loaded cut; the policy was trained on a different LP{n} and {m} count stored bases, one per node and forward-pass scenario, and {node} is the node of the
first that does not fit, by node position and then scenario. {reason} is one of
{found} columns, the LP has {expected}, {found} rows, the LP expects {expected},
{found} basic entries for {expected} rows or a cut row at slot {slot}, which holds no loaded cut.
novomodelo run prints it as warning: {message} on stderr (--quiet hides it); novomodelo validate prints
warning: <output dir>/<policy.path>: {message}, and --json gives the count as
policy_load.unused_stored_bases. Python prints novomodelo-python: policy validation warning: {message}. The exit
code is unaffected.
SimulationPolicyIncompatible
Seção intitulada “SimulationPolicyIncompatible”novomodelo validate reports a refused load of a simulation-only run (training.enabled = false with simulation
scenarios) as its phase, whatever policy.mode is, with the message labelled <output dir>/<policy.path>: ,
and exits 1; a checkpoint the OS refuses to read reports IoError and exits 2. The same kind carries the
load’s warnings, which exit 0: Stored bases not used and the two entity-manifest
warnings quoted under WarmStartIncompatible.
Policy-load errors gives the refusal messages. For example, a simulation-only run with no
checkpoint at policy.path reports:
<output dir>/<policy.path>: Policy directory not found: <output dir>/<policy.path>. Cannot run simulation-only mode without a trained policy.NotImplemented
Seção intitulada “NotImplemented”Severity: Error
When it occurs: Two or more hydros that declare a positive
travel_time_hours feed the same downstream plant with values that differ by
more than 1e-9, and at least one study stage in stages.json uses
"chronological" block_mode. The
check rejects the case whenever any study stage is chronological, not only the
stages where the arcs’ timing would differ. Emitted by the business-rule check,
with one line for each affected downstream plant, on system/hydros.json.
Example:
Hydro {downstream_id}: chronological confluence with heterogeneous travel times is unsupported in v1 — {n} declared arcs feed this downstream plant with differing travel_time_hours ({arcs}); align the arcs' travel_time_hours or keep every study stage in Parallel mode{downstream_id} is the id of the downstream plant, {n} is the number of arcs
that feed it, and {arcs} lists those arcs as comma-separated
hydro {id} (travel_time_hours={t}) items.
Resolution: Give every arc into that downstream plant the same
travel_time_hours in
system/hydros.json, or
set block_mode to "parallel" on every study stage in
stages.json.
UnusedEntity
Seção intitulada “UnusedEntity”Severity: Warning (does not block execution)
When it occurs: A contract_import or contract_export term of a
generic constraint names a contract id that system/energy_contracts.json does
not declare. The term has no effect and the case still loads. The warning alerts
the user to a possible input error.
Example:
{label} references Contract {id} which is a stub entity with no LP effect{label} is GenericConstraint N term[M], naming the constraint id and the
zero-based position of the term in its expression; {id} is the undeclared
contract id.
Resolution: Correct the contract id in the term, or declare that contract in
system/energy_contracts.json. If the term is intentional, this warning can be
ignored.
ModelQuality
Seção intitulada “ModelQuality”Severity: Warning (does not block execution)
When it occurs: A concern about the input model is detected that leaves
the case valid. Examples: an inverted penalty ordering, an FPHA price at or below the largest
deficit cost plus the minimum-generation price, inflow-lag state
disabled on every study stage despite supplied autoregressive coefficients, a
negative value in scenarios/inflow_history.parquet, a season with none of
the samples the estimation fits from that file, a hydro-season with at least one, but fewer than
estimation.min_observations_per_season, fully covered season occurrences in that
file, an advisory on a hydro’s declared travel_time_hours, a hard storage floor that rises above the floor the previous stage leaves, a precomputed FPHA plane that falls below 0 MW at zero turbined flow, or an initial
storage outside the storage bounds at the end of the hydro’s first operating
stage. Each is reported as a warning.
Example:
warning: penalties.json: Penalty ordering violation: max(deficit_segment_costs) (7500) should be > generation_violation_below_cost (10000) (both $/MWh) -- 1 hydro(s) affected, worst case: Hydro 0The cost-ordering warnings start Penalty ordering violation:, and the FPHA
price warning starts FPHA price ordering violation:. All four messages are
quoted under
Load-time penalty checks.
The inflow-lag message:
inflow lags are disabled on all study stages (state_variables.inflow_lags = false) despite a PAR(p>0) inflow model (AR order {max_order}), so the inflow-lag dimensions are omitted from the per-stage state. This is a valid configuration for external-solver interoperability; otherwise it is likely a misconfiguration{max_order} is replaced by the AR order when the warning is issued. When it
fires and what it changes:
stages[].state_variables — Cut Projection.
The observation-count message:
hydro {hid} season {sid} has {n} observations (minimum recommended: {min_obs}); estimation accuracy may be insufficient with so few observations{min_obs} is estimation.min_observations_per_season. novomodelo validate reports
the warning only when the inflow model is estimated from
scenarios/inflow_history.parquet (that is, the case does not supply both
scenarios/inflow_seasonal_stats.parquet and scenarios/inflow_ar_coefficients.parquet)
and stages.json declares season_definitions. {n} counts the fully covered
season occurrences the estimation fits from, inside or outside the study horizon;
with estimation.history_years set, only those that start in its years.
The initial-storage messages, reported on initial_conditions.json for the hydro:
Hydro {id}: initial storage ({value}) lies below the minimum storage ({min}) at the end of stage {stage_id}, its first operating stage; that stage must reach it from its own inflowHydro {id}: initial storage ({value}) lies above the maximum storage ({max}) at the end of stage {stage_id}, its first operating stage; that stage must release the excessThe first operating stage is the first study stage inside the hydro’s
commissioning window. Its bounds are the stage-level row (block_id null) of
constraints/hydro_bounds.parquet for that hydro and stage, else the hydro’s
own min_storage_hm3 and max_storage_hm3. A hydro with a filling
configuration is not checked. The initial storage is kept as declared.
The rising-floor message, reported on constraints/hydro_bounds.parquet:
Minimum storage rises above the previous stage's floor at {} (hydro, stage) pair(s), so a stage whose inflow cannot cover the rise is infeasible: {pairs}Each pair is written Hydro {hydro_id} at stage {stage_id} ({floor} > {incoming}). The pairs are sorted by hydro id, then stage id, and joined with , . The check runs under the truncation, truncation_with_penalty and none inflow methods and is silent under penalty. The hard floor is 0 for a filling hydro and at a PreFilling stage, and the stage’s resolved min_storage_hm3 otherwise. The stage that receives the initial storage is left to the initial-storage message.
The precomputed-plane message, reported on system/fpha_hyperplanes.parquet for the hydro:
FPHA plane below zero at zero turbining: {entity} -- {n_pairs} (stage, plane) pair(s) at stages {stages} fall below 0 MW with no turbined flow; the earliest crosses 0 MW at {s_star} m³/s of spillage (stage {stage_id}, plane {plane_id}, storage {v_min} hm³, spillage up to {s_ref} m³/s), so while it spills the hydro turbines water at 0 MW, or reports fpha_violation_mw where turbining cannot lift the plane to 0 MWThe check skips a hydro with no FPHA entry, a hydro whose FPHA is computed (source: "computed") and a hydro without turbine capacity. It covers each study stage whose entry resolves to fpha, and a stage uses its own stage_id rows, else the all-stage (stage_id null) rows. It evaluates each row at zero turbined flow, at the fitting window’s minimum storage and at the upper end of the spillage fit range (spillage_fit_max_m3s, or its default), with kappa multiplying gamma_0 only. {s_star} is the spillage at which the plane reaches 0 MW, (kappa·gamma_0 + gamma_v·v_min)/|gamma_s| when that sum is positive and 0 otherwise. The earliest crossing is the smallest {s_star}, with ties broken by stage id and then plane id. {stages} lists the flagged stage ids as ascending runs written a-b (or a single id) and joined by , . One warning is reported per hydro.
Resolution: Review the flagged input. For a penalty-ordering warning, see
Load-time penalty checks; for the
inflow-lag warning, see
stages[].state_variables — Cut Projection;
for the initial-storage warning, check that the first operating stage can reach
its storage bounds, or move the initial storage inside them; for the rising-floor warning, lower the rising floor, raise the previous stage’s floor, or use the penalty inflow method (see the complete-recourse precondition); for the precomputed-plane warning, raise the flagged plane’s gamma_s to at least −(kappa·gamma_0 + gamma_v·v_min)/S_ref, with the storage v_min and the spillage S_ref the message prints, or fit the planes from geometry with source: "computed", whose planes get this limit (Lateral-Flow Secant); a plane whose crossing is at 0 m³/s needs a larger gamma_0 or gamma_v.
Warnings of this type do not prevent the solver from running.
SemanticAmbiguity
Seção intitulada “SemanticAmbiguity”Severity: Warning (does not block execution)
When it occurs: A valid construct whose semantics are ambiguous or
stage-dependent in a way that is likely to surprise the user. Two constructs
trigger it, both emitted by the business-rule check in
constraints/generic_constraints.json:
-
thermal_generation(N)on an anticipated thermal. Usingthermal_generation(N)in a generic constraint when thermalNis an anticipated thermal.thermal_generationrefers to the per-block generation measured at the delivery stage (when the commitment matures), not the commitment decision made at the current stage. Users who intend to constrain the commitment itself should useanticipated_decision(N)instead.Example: A generic constraint
thermal_generation(0)on an anticipated thermal:warning: constraints/generic_constraints.json (constraint[id=0]): Constraint "peak_cap": thermal_generation(0) references an anticipated thermal. thermal_generation refers to the per-block generation at the delivery stage, not the forward commitment. If you intend to constrain the commitment itself, use anticipated_decision(0) instead.Resolution: Review the constraint expression. If you want to bound the generation dispatched at the delivery stage,
thermal_generation(N)is correct and the warning can be ignored. If you want to bound the advance commitment decision itself, replacethermal_generation(N)withanticipated_decision(N). -
Stored-energy tags that would not cancel. One constraint references computed tags — in its expression coefficients, in its bounds (an
@emaxon the right-hand side counts) or through anexpressionparameter that reads them — in one of two forms:- a
max_stored_energy(h)ceiling beside a productivity tag for the same hydro other thanintegrated_accumulated_productivity(h)(or amax_stored_energy_mwh(h)ceiling beside an MWh productivity tag other thanintegrated_accumulated_productivity_mwh_per_hm3(h)). The tags differ in scope (one plant or its downstream cascade) or in evaluator (the plant’s reference point or the useful-range mean), so a stored-energy comparison built from them does not cancel. One warning is emitted per such pair. - MWh tags (the
_mwhand_mwh_per_hm3family) mixed with raw tags. The two families differ by a factor of ; the warning readsConstraint "<name>": mixes MWh tags (<tags>) with raw productivity tags (<tags>); the two units differ by a factor of 10^6/3600. Use one family throughout.
The case still validates.
Example: A constraint that pairs the two tags for hydro 0:
warning: constraints/generic_constraints.json (sec_mismatch): Constraint "sec_mismatch": pairs max_stored_energy(0) with accumulated_productivity(0) for hydro 0; the two differ in scope or evaluator and would not cancel. The coefficient matching max_stored_energy is integrated_accumulated_productivity.Resolution: Use
integrated_accumulated_productivityas the coefficient that matchesmax_stored_energy, orintegrated_accumulated_productivity_mwh_per_hm3withmax_stored_energy_mwh, and keep one constraint in one family; see the security-curve example. - a
The warning is printed by novomodelo validate in its human-readable output; the
--json success output does not carry warnings.
Load-failure kinds
Seção intitulada “Load-failure kinds”The phase value of novomodelo validate --json and the kind of an entry in the errors array of
novomodelo.io.validate (Python) name the failure that stopped the load. Almost every case-load failure reports
ConstraintError, because the load collects its problems into one report. The kinds are
listed below in the order of the load steps in which they typically occur: reading a file, parsing it,
checking its fields, then validating the whole case.
During a case load, a read, parse or schema failure in one file is collected
into the validation report rather than returned on its own. It reaches you as a
line of a ConstraintError: [FileNotFound] for a read
failure, [ParseError] <file>: parse error: <message> for a parse failure, and
[SchemaViolation] <file>: field <field>: <message> for a schema failure. The
display formats below reach you only for a load error raised after that report
is complete, such as a policy.path refusal raised once the case has loaded; see Exit Codes.
IoError
Seção intitulada “IoError”Severity: Error
When it occurs: A required file exists in the file manifest but cannot be
read from disk — file not found, permission denied, or other OS-level I/O
failure. Occurs when a JSON or Parquet file is read for parsing and the read
returns an error. It is also returned when a policy.path cannot be inspected (exit 2).
Display format:
I/O error reading {path}: {source}Fields:
| Field | Description |
|---|---|
path | Path to the file that could not be read |
source | Underlying OS I/O error |
Resolution: Verify the file exists in the case directory. Check that the process has read permissions for the directory and file. For a full case load, the case root must contain all required files (see Case Format). A problem collected during a case load prints as a report line; see Validation report kinds.
ParseError — see ParseError; a parse failure collected in the report prints as a
[ParseError] line.
SchemaError
Seção intitulada “SchemaError”Severity: Error
When it occurs: A file parses successfully but a field violates a schema
constraint: a required field is missing, a value is outside its valid range, or
an enum discriminator names an unknown variant. Occurs when the fields of a parsed
file are checked. Also returned when training.selection
(which carries the forward-pass count) or training.stopping_rules is absent
and the config is parsed or merged outside a case load (for example, Python
config overrides); a case load reports the same absence as a
SchemaViolation line. It is also returned for a policy.path that the run refuses after the case loads (exit 1; see
Configuration — policy).
Display format:
schema error in {path}, field {field}: {message}Fields:
| Field | Description |
|---|---|
path | Path to the file containing the invalid entry |
field | Dot-separated path to the offending field (e.g., "hydros[3].bus_id") |
message | Human-readable description of the violation |
Resolution: The field value identifies the exact location of the problem.
Check that required fields are present and that values fall within documented
ranges. A problem collected during a case load prints as a report line; see Validation report kinds.
ConstraintError
Seção intitulada “ConstraintError”Severity: Error
When it occurs: A catch-all for all validation diagnostics collected
across any validation step, for system assembly rejections, and for guards
raised directly by loaders after assembly (for example, a non-finite
closure-derived innovation scale is rejected here naming the hydro and
season). The description field contains
every collected error message joined by newlines, each prefixed with its
[<Kind>], source file, optional entity identifier, and message text.
Display format:
constraint violation: {description}Fields:
| Field | Description |
|---|---|
description | All error messages joined by newlines |
Example: The --json failure capture under
How these errors reach you reports ConstraintError as its
phase, with the collected report line in message.
Resolution: Read every line in description — each line is a separate
problem. Address them all and re-run. The [<Kind>] prefix identifies the
category of each problem, and each kind section gives its resolution. A problem collected during a case load prints as a report line; see Validation report kinds.
Preparation-phase kinds
Seção intitulada “Preparation-phase kinds”The six phase values below appear only in novomodelo validate’s pre-solver
validation checks and are not LoadError kinds. They surface in
novomodelo validate --json’s error phase field when a prep-phase check fails
before the solver is initialized.
ConfigValidationError
Seção intitulada “ConfigValidationError”Severity: Error
When it occurs: A config.json validation failure in the study-setup
preparation phase, after the config has been parsed and before stochastic model
setup begins. File label: config.json.
Example: A gap stopping rule with neither tolerance nor
relative_tolerance:
config.json: configuration validation error: gap stopping rule requires at least one of tolerance / relative_tolerance to be presentCut-selection configuration refusals
Seção intitulada “Cut-selection configuration refusals”training.cut_selection is checked in three places. A value its schema refuses prints a [ParseError] line
when the case loads; a rule between two of its fields reports ConfigValidationError; a pairing with another
setting reports StudySetupError (or BoundaryReconciliationError with policy.boundary
configured). Each exits 1. Configuration — training.cut_selection
states the rules.
| Setting | Reported as | Message |
|---|---|---|
selection given as an array | [ParseError] | config.json: parse error: invalid type: sequence, expected internally tagged enum SelectionMethod |
A count parameter set to 0 | [ParseError] | config.json: parse error: training.cut_selection.selection.check_frequency must be >= 1 (got 0), naming the key set to 0 |
method "lml1" or "domination" | [ParseError] | config.json: parse error: the row-selection method `lml1` was removed: use `level1` (key `training.cut_selection.selection.method`) |
tie_tolerance under level1 | [ParseError] | config.json: parse error: the key `tie_tolerance` was removed: `level1` compares row values exactly; delete the key (`training.cut_selection.selection`) |
row_activity_tolerance null | [ParseError] | config.json: parse error: invalid type: null, expected f64 |
A misspelled method | [SchemaViolation] | config.json: field dynmic: unknown variant `dynmic`, expected `level1` or `dynamic` |
lookback_iterations below check_frequency | ConfigValidationError | config.json: configuration validation error: cut_selection config error: cut_selection.lookback_iterations (2) must be >= cut_selection.check_frequency (5) |
row_activity_tolerance negative | ConfigValidationError | config.json: configuration validation error: cut_selection config error: cut_selection.row_activity_tolerance must be finite and >= 0 (got -1) |
violation_tolerance 1 or more | ConfigValidationError | config.json: configuration validation error: cut_selection config error: cut_selection.violation_tolerance must be < 1 (got 1) |
violation_tolerance below a phase’s primal feasibility tolerance | StudySetupError | config.json: configuration validation error: training.cut_selection.selection.violation_tolerance (0.000000000001) is a relative factor and must be at least the primal feasibility tolerance of the backward solver profile (0.000000001); raise it, or omit it to use each phase's solver tolerance |
max_active_per_stage with dynamic | StudySetupError | config.json: configuration validation error: training.cut_selection.max_active_per_stage is inadmissible with the dynamic cut selection method; a lazy solve takes its candidates from the active rows and dynamic runs no selection pass, so an evicted row never returns — remove the cap, or use the `level1` method |
The method domination prints its own name in the removed-method message. Two pairings with an enumerated
training.selection report StudySetupError as well:
dynamic cut selection is inadmissible under enumerated forward traversal; the enumerated backward never solves lazily and records no binding activity, so the seed window of the enumerated forward's lazy solve would never advance past a cut's generating iteration — pair enumerated forwards with the `level1` method, or with no selection methodtraining.cut_selection.max_active_per_stage is inadmissible under enumerated forward traversal; enumerated traversal records no binding activity, so the cap would evict by generation order alone — remove the cap, or use sampled forward selectionA cap below training.selection.forward_passes is accepted with a warning, which novomodelo validate and
novomodelo run log on stderr as a WARN line, apart from the report on stdout:
WARN max_active_per_stage (1) is less than forward_passes (4): in a stage whose row pool receives 4 rows per iteration, the cap evicts at every iteration every row this run added in an earlier iteration; rows loaded from a policy are not affectedStochasticPreparationError
Seção intitulada “StochasticPreparationError”Severity: Error
When it occurs: A failure during stochastic model preparation — scenario
generation, inflow-model setup, or external scenario validation. File label:
scenarios/inflow_history.parquet for a stochastic-model error (after the label,
its message begins stochastic error:) and scenarios/ for every other failure
in this phase, such as a load error (after the label, its message begins
I/O error:). The label depends on how the error is classified, not on the file
it traces to.
Example: A historical library that holds no complete window, a non-stationary inflow model (non-finite innovation scale), an autoregressive stage whose standard deviation is zero, a stage with more openings than the first stage of its noise group, or a declared opening-tree file that is absent. Historical-library refusals, Inflow-model refusals, Noise-group opening count and Opening-tree file missing quote the messages.
Historical-library refusals
Seção intitulada “Historical-library refusals”When it occurs: Three refusals of the historical window pool are reachable
from a case. The pool serves the forward historical scheme and the stages that
use the historical_residuals sampling method (see
Historical Window Pool and
Historical-Residual Openings).
Each message is insufficient data: followed by the text below:
- No year is admissible, so the pool is empty:
no valid historical windows found: ensure that inflow history covers the required seasons for at least one starting year
- A study stage has no season:
V2.1: stage {stage_id} (index {index}) has season_id: None; all study stages must have a season_id assigned
- A residual of the pool is not finite:
V2.3: historical library contains non-finite eta (NEG_INFINITY or NaN) at window year {year}, stage id {stage_id}, hydro id {hydro_id} — sigma=0 with non-matching historical observation or numerical failure
V2.1 names the stage id, then the stage’s 0-based index. A stage has no season
when it declares none and the case either has no season definitions or has a
custom season map that leaves the stage’s start date uncovered. For example,
with an inflow model of order 1 and a custom season map that covers the first
stage and its lag season but leaves one later stage’s start date uncovered,
novomodelo validate reports V2.1.
V2.3 names the window’s year, the stage id and the hydro id.
Rendering under novomodelo validate: the phase is StochasticPreparationError
and the exit code is 1. The error: line carries the file label and the
stochastic error: prefix. This excerpt omits the Validation: summary line,
which carries the case path.
error: scenarios/inflow_history.parquet: stochastic error: insufficient data: no valid historical windows found: ensure that inflow history covers the required seasons for at least one starting yearnovomodelo run on the same case exits 1. The line has no file label, and the
validate hint follows it. This excerpt omits the banner, the Execution block and the
Loading case: line.
error: stochastic error: insufficient data: no valid historical windows found: ensure that inflow history covers the required seasons for at least one starting year -> run `novomodelo validate <CASE_DIR>` for a full diagnostic reportnovomodelo validate builds the study as novomodelo run does, so it reports a refusal
of the forward historical scheme’s library too: as
StudySetupError (scenarios/: stochastic error: …) without
policy.boundary, and as
BoundaryReconciliationError
(policy.boundary: …) with it; both commands exit 1.
When a stage also uses historical_residuals, the refusal is reported as rendered above, with or without
policy.boundary.
Inflow-model refusals
Seção intitulada “Inflow-model refusals”When it occurs: The inflow model, declared by the case’s autoregressive and
statistics files or fitted from inflow_history.parquet, cannot support the
study. Two refusals carry a fixed message:
- An autoregressive stage has a standard deviation of zero. The message names
the hydro id and the stage id, and
ar_orderis the stage’s autoregressive order:This is a stochastic-model error.invalid PAR parameters for hydro {hydro_id} at stage {stage_id}: zero standard deviation with ar_order={ar_order}: AR model requires nonzero variance to normalize coefficientsnovomodelo validateprints it after thescenarios/inflow_history.parquet: stochastic error:prefix and exits1.novomodelo runprints it aserror: stochastic error: invalid PAR parameters …with the validate hint, and exits1. - The model’s coefficients imply a non-stationary process, so a derived
residual standard-deviation ratio is not finite. A model fitted from the
history does not reach this refusal: the fit lowers the order of a season whose
model implies a negative residual variance, and
fitting_report.jsonlists it asnegative_residual_variance. The message names the hydro id and the season id:This is aI/O error: constraint violation: derived residual_std_ratio is non-finite for hydro_id={hydro_id} season={season}: the coefficients imply a non-stationary process (implied residual variance 1 - sum(psi*rho) is negative)ConstraintErrorraised while the model is assembled, so it reaches the command as a load error.novomodelo validateprints it with thescenarios/file label and exits1.novomodelo runprints it without theI/O error:prefix, followed by a hint to runnovomodelo validate, and also exits1.
Noise-group opening count
Seção intitulada “Noise-group opening count”When it occurs: A study stage has more openings than the first stage of its
noise group, the run of adjacent study stages with the same season_id whose
start dates fall in one calendar year
(Scenario Generation §2.3). The
counts compared are the ones the opening tree uses: num_openings after the
clamps by a historical window pool and by an external scenario library (the
clamp warnings of the Implementation notes tab of
Scenario Generation),
so a clamp on the first stage alone can bring it about. The check runs before
any noise is drawn. The message names both stages:
insufficient data: stage {dst_id} has {k_dst} openings but shares a noise group with stage {src_id}, which has {k_src}; a stage cannot have more openings than the first stage of its noise group: lower num_openings of stage {dst_id} in stages.json to {k_src}This is a stochastic-model error. novomodelo validate prints it after the
scenarios/inflow_history.parquet: stochastic error: prefix and exits 1.
novomodelo run prints it as error: stochastic error: insufficient data: stage …
with the validate hint, and exits 1.
Resolution: Lower num_openings of the named stage in stages.json to the
count the message gives. When a clamp lowered the first stage’s count, more
historical windows or external scenarios for that stage also clear the refusal.
A later stage with fewer openings than the first stage is accepted and copies
the first of them.
Opening-tree file missing
Seção intitulada “Opening-tree file missing”When it occurs: training.scenario_source.openings is {"source": "file"}
and scenarios/noise_openings.parquet is absent. The stochastic preparation
phase of novomodelo validate stops with exit 2, as novomodelo run does, and under --json the error’s phase is
StochasticPreparationError. The message is:
openings source is 'file' but the conventional scenarios/noise_openings.parquet is absentExample: novomodelo validate prints the message inside an I/O error line. The
scenarios/ label and the I/O error: wording are how this phase reports a
missing file, and <case> stands for the path of your case directory:
error: scenarios/: I/O error: I/O error reading <case>/scenarios/noise_openings.parquet: openings source is 'file' but the conventional scenarios/noise_openings.parquet is absenterror: I/O error in <case>/scenarios/noise_openings.parquet: openings source is 'file' but the conventional scenarios/noise_openings.parquet is absent -> check that the path exists and you have read/write permissionsResolution: Supply scenarios/noise_openings.parquet, or declare openings
as {"source": "generated"}. Configuration
describes the openings key.
StudySetupError
Seção intitulada “StudySetupError”Severity: Error
When it occurs: Study construction fails on a case without policy.boundary: a scenario library (the
forward historical scheme’s included), an external-library check, a solver-profile check, or the admission
gate of the gap rule and of the dynamic selection method and max_active_per_stage. File label: scenarios/ for a stochastic-model error,
config.json otherwise. On a case with policy.boundary, the same failures report
BoundaryReconciliationError. novomodelo validate exits 1.
Example:
scenarios/: stochastic error: insufficient data: no valid historical windows found: ensure that inflow history covers the required seasons for at least one starting yearHydroModelsPreparationError
Seção intitulada “HydroModelsPreparationError”Severity: Error
When it occurs: A failure during computed-FPHA fitting or hydro production
model preparation. File label: system/hydro_production_models.json.
Example: A plant whose generation.model is fpha and that has no entry in
system/hydro_production_models.json:
system/hydro_production_models.json: configuration validation error: hydro UHE1 (id=0) has generation_model: "fpha" in hydros.json but no entry in hydro_production_models.json. Add an entry with source: "precomputed" to specify the hyperplane source.On a plant with a source: "computed" entry, every study stage that resolves to
the fpha model needs an entry with an fpha_config. A stage that no entry
covers, on a plant whose generation.model is fpha, or a season that falls
back to a default_model of "fpha", is refused with:
system/hydro_production_models.json: configuration validation error: hydro <name> (id=<id>) has source: "computed" but no FphaColumnLayout covers stage <stage_id> in hydro_production_models.jsonGenericConstraintValidationError
Seção intitulada “GenericConstraintValidationError”Severity: Error
When it occurs: A failure during generic-constraint preparation, including
expression inlining, parameter resolution, and slack setup. File label:
constraints/.
An unresolved @parameter scalar — a generic-constraint parameter
declared in constraints/generic_parameters.json that has no value for a
season, stage or block the study needs — fails here at novomodelo validate time.
An @name that no file declares is reported at load time; see
Generic-constraint expression rejected.
The parameter is refused with one of:
parameter '<name>': no seasonal value for season_id=<season> (needed by stage <t>)parameter '<name>': PerStageBlock cell (stage=<s>, block=<b>) is not covered by any tripleparameter '<name>': PerStageBlock cell (stage=<s>, block=<b>) lies outside the study's (stage, block) gridparameter '<name>': no specific productivity (`ρ_esp`) available for hydro_id=EntityId(<id>)<t> and <s> are 0-based study stage positions and <b> a 0-based block
index. A seasonal parameter needs a value for the season of every study
stage, and a per_stage_block parameter a value for every block of every study
stage. A computed parameter with the specific_productivity tag needs a
specific_productivity_mw_per_m3s_per_m for its hydro at every study stage,
from system/hydro_energy_productivity.parquet or from system/hydros.json.
A non-finite resolved value fails here too. A coefficient, a bound or an
expression parameter that depends on scalar parameters is evaluated at every
stage and block it is active in, and one whose value is not finite there (a
division by a parameter that is zero at that stage, for instance) is refused
with one of:
generic constraint <id> '<name>': the coefficient of <variable> resolves to the non-finite value <value> at stage <s>, block <b>generic constraint <id> '<name>': the upper bound resolves to the non-finite value <value> at stage <s>, block <b>parameter '<name>': expression resolves to the non-finite value <value> at stage <s>, block <b>The bound message names the lower or the upper bound; an expression
parameter is checked whether or not a constraint reads it. A constant built from
numbers alone that divides by zero is refused at load instead; see
Generic-constraint expression rejected.
Example: A seasonal parameter whose only value is for season 5, in a case with
no season definitions:
constraints/: configuration validation error: parameter 'sea': no seasonal value for season_id=0 (needed by stage 0)This phase also reports energy-conversion failures of a hydro plant computed
at the same step — a forebay (VHA) table in system/hydro_geometry.parquet that
fails to build, or a non-positive useful-range mean equivalent head — for any
plant with VHA geometry and a specific productivity, independent of its
generation model and of whether the case declares generic constraints (see
Hydro Production Function Models §4.3).
An equivalent_productivity_mw_per_m3s value in
system/hydro_energy_productivity.parquet sets only the reference-point
productivity and does not avoid the mean-head check; an
integrated_equivalent_productivity_mw_per_m3s value for the stage does, and
the message names that column.
A plant whose geometry and losses leave a negative head:
constraints/: configuration validation error: hydro EntityId(0) has non-positive useful-range mean equivalent head h_mean=-50; fix its geometry/tailrace or supply integrated_equivalent_productivity_mw_per_m3s in system/hydro_energy_productivity.parquetBoundaryReconciliationError
Seção intitulada “BoundaryReconciliationError”Severity: Error
When it occurs: A failure when reconciling an injected boundary policy with
the current study. File label: policy.boundary.
Example: A boundary checkpoint written by another software or version reports the message of
PolicySoftwareMismatch prefixed with the file label:
policy.boundary: policy was written by {writer}, but this is novomodelo {running}; a policy loads only in the software and version that wrote it: re-run the program that produced it with novomodelo {running}; for a converted boundary policy, convert it againThe phase reports a refusal from any of the boundary checks listed under
Compatibility requirements
once the checkpoint is read. A checkpoint that cannot be read reports in this phase too, as
policy.boundary: configuration validation error: failed to read boundary policy checkpoint at {path}: {e} (exit 1; --json prints the object).
On a case with policy.boundary, every study-construction failure reports this phase and label.
Policy-load errors
Seção intitulada “Policy-load errors”A policy load refuses a checkpoint that does not fit the study loading it. Two
loads raise these errors: a full-FCF load of the checkpoint at policy.path
(warm-start, resume, and simulation-only runs) and a boundary load of the
checkpoint at policy.boundary.path. novomodelo run and the Python entry points
raise them before training or simulation starts. novomodelo validate runs both loads the run would apply, reading the full-FCF checkpoint from <output dir>/<policy.path> (--output, default <CASE_DIR>/output/), and exits 1 on every refusal novomodelo run makes. These errors are not
LoadError variants, and case loading does not return them.
A full-FCF load runs its checks in the order given under
Check order. The checks of a boundary
load are listed under
Compatibility requirements.
A manifest.bin whose format_version is not 4 fails before these checks:
failed to read policy checkpoint: serialization error for entity checkpoint_manifest: unsupported checkpoint manifest format_version {n}; expected 4; re-run the program that produced it with novomodelo {running}; for a converted boundary policy, convert it again, exit 1.
How a policy-load failure reaches you
Seção intitulada “How a policy-load failure reaches you”| Channel | Refusal | Unreadable or missing checkpoint |
|---|---|---|
novomodelo run, full-FCF load | Exit 1. error: {message} and the validate hint on stderr. | Exit 1: error: Policy directory not found: {path}. {requirement} or error: failed to read policy checkpoint: {e}. Exit 2 for a checkpoint the OS refuses to read: error: I/O error in {path}: {source} and the permissions hint. |
novomodelo validate, full-FCF load | Exit 1. Validation: 1 errors, 0 warnings in <case> and error: <output dir>/<policy.path>: {message}; --json phase WarmStartIncompatible, ResumeIncompatible or SimulationPolicyIncompatible. | Exit 1 (phase as for a refusal), or exit 2 with phase IoError for a checkpoint the OS refuses to read. |
novomodelo run and novomodelo validate, boundary load | Exit 1. novomodelo run prints error: {message} and a hint line. novomodelo validate labels the message policy.boundary: ; under --json it reports phase BoundaryReconciliationError. | Exit 1. error: failed to read boundary policy checkpoint at {path}: {e} and a hint line on stderr. Under novomodelo validate --json, phase BoundaryReconciliationError. |
Python, full-FCF load (novomodelo.run.run, Study.train, Study.load_policy) | PolicyIncompatibleError. The message starts policy validation error: . | ValidationError for a missing directory, PolicyIncompatibleError for a read or decode failure, CaseIoError for a read the operating system refuses. The message is Policy directory not found: {path}. {requirement} or failed to read policy checkpoint: {e}, with no prefix. |
Python, boundary load (novomodelo.run.run, Study, Study.train) | novomodelo.run.run and Study.train raise PolicyIncompatibleError for a version mismatch, with the message prefix policy validation error: , and ValidationError for every other refusal, with the message prefix boundary cut error: . Study(...) constructs without error on a checkpoint it can read. | ValidationError. The message starts setup validation error: . It is raised when the study is built, before training. |
novomodelo.results.load_policy | No refusal: it reads a checkpoint of any novomodelo version without comparing it with a study. | FileNotFoundError for a missing directory or a missing manifest.bin. OutputError for a file whose content cannot be decoded. |
{requirement} names the run mode: Cannot warm-start without a prior policy.,
Cannot resume without a prior checkpoint., or
Cannot run simulation-only mode without a trained policy.
PolicySoftwareMismatch
Seção intitulada “PolicySoftwareMismatch”Severity: Error
When it occurs: A full-FCF load or a boundary load reads a checkpoint whose
manifest.bin records another software or version than the running build: the
software and software_version compare exactly, so a different patch or
pre-release build is refused as well. A checkpoint whose format_version is not
4 is refused before this check
(How a policy-load failure reaches you).
Version gate states the rule.
Message:
policy was written by {writer}, but this is novomodelo {running}; a policy loads only in the software and version that wrote it: re-run the program that produced it with novomodelo {running}; for a converted boundary policy, convert it again{writer} is <software> <version>, <software>, which recorded no version,
software that recorded no name, version <version> or software that recorded no name or version;
{running} is the version of the novomodelo that loads it.
Python class: Python raises
PolicyIncompatibleError with the message prefix policy validation error: ,
for a full-FCF load and for a boundary load. Under novomodelo validate --json, a
boundary checkpoint written by another software or version reports phase
BoundaryReconciliationError and the message prefixed policy.boundary: .
Resolution: Re-run the program that produced the checkpoint with the running novomodelo version; for a converted boundary policy, convert it again. Version gate describes both routes.
Structural mismatch
Seção intitulada “Structural mismatch”When it occurs: A full-FCF load finds a checkpoint pool that records no cost scale or one that is not a finite positive number, or a checkpoint that describes a different state space or study graph than the current study. The cost-scale check is step 2 of the check order and the state and graph checks are step 4. The entity-identity and graph checks run only when both sides carry the manifest.
Messages:
Cost scale (step 2):
policy checkpoint predates self-describing cuts (its cuts/<pool>.bin for pool {pool} carries no cost_scale_factor); re-run the program that produced it with novomodelo {running}; for a converted boundary policy, convert it againpolicy checkpoint pool {pool} records cost_scale_factor {factor}, which is not a finite positive number; re-run the program that produced it with novomodelo {running}; for a converted boundary policy, convert it again{pool} is the pool’s stage id, and the first pool that fails is reported.
State and graph (step 4):
policy state_dimension mismatch: policy has {n}, current system has {n} (a lag-state depth mismatch is a common cause)policy num_stages mismatch: policy has {n}, current system has {n}policy n_pools mismatch: policy has {n}, current system has {n}entity manifest length mismatch: source has {n} slots, current study has {n}entity-identity mismatch at slot {i}: source (entity_type={t}, entity_id={id}, subindex={s}) != current (entity_type={t}, entity_id={id}, subindex={s}); the cut coefficient at this slot would attach to the wrong state variablegraph manifest n_pools mismatch: source has {n}, current study has {n}graph manifest node-count mismatch: source has {n} nodes, current study has {n}graph manifest node {i} mismatch: source (id={id}, stage_id={id}, pool_id={id}) != current (id={id}, stage_id={id}, pool_id={id})graph manifest edge-count mismatch: source has {n} edges, current study has {n}graph manifest edge {i} mismatch: source ({source_id} -> {target_id}) != current ({source_id} -> {target_id})A boundary load refuses a resolved pool without a cost_scale_factor with its
own message, and one whose factor is not a finite positive number with the
records cost_scale_factor message above:
boundary policy checkpoint at {path} predates self-describing cuts (its resolved cuts/<pool>.bin carries no cost_scale_factor); re-run the program that produced it with novomodelo {running}; for a converted boundary policy, convert it againPython class: Python raises
PolicyIncompatibleError with the message prefix policy validation error: for
the full-FCF messages, and ValidationError with the message prefix
boundary cut error: for the boundary message.
Resolution: Train a new policy for the changed study or restore the matching inputs; see Check order. For a cost-scale refusal, re-run the program that produced the checkpoint with the running novomodelo version, as its message states.
Resume refusals
Seção intitulada “Resume refusals”When it occurs: A policy.mode = "resume" load finds that the checkpoint cannot continue the interrupted
run identically. The five checks run after the structural checks, in the order of
Resume refusals, and the first that fails stops the run with
phase ResumeIncompatible. A warm_start load of the same checkpoint makes none of these checks.
Messages:
resume needs the forward-pass count the checkpoint was written with: training.selection.forward_passes is {run} here and {stored} in the checkpoint; set it to {stored} or continue with policy.mode = warm_startresume needs the trial-state history of training.cut_selection.selection.method = level1; the checkpoint holds none (it was written by a run without level1 or exports.states); continue with policy.mode = warm_start or retrainresume needs every trial state of the run under training.cut_selection.selection.method = level1 without lookback_iterations; the checkpoint holds those of the last {stored} iterations only; set lookback_iterations to at most {stored} or continue with policy.mode = warm_startresume needs the trial states of the last {window} iterations (training.cut_selection.selection.lookback_iterations = {window}); the checkpoint holds those of the last {stored} iterations only; set lookback_iterations to at most {stored} or continue with policy.mode = warm_startresume needs the binding counters read by {reader}; the checkpoint holds none (it was written by a run without max_active_per_stage or the dynamic method); continue with policy.mode = warm_start or retrainresume needs a whole checkpoint; the checkpoint's per-scenario bases are not whole (it was written when a run failed); resume from the last whole checkpoint or continue with policy.mode = warm_start{reader} is training.cut_selection.max_active_per_stage when the cap is set, and
training.cut_selection.selection.method = dynamic otherwise. A resume of a run that declared policy.boundary
is also refused when the boundary rows differ from the checkpoint’s; the message is quoted under
Resuming with a boundary.
novomodelo validate labels each message <output dir>/<policy.path>: configuration validation error: . For example,
a resume with training.selection.forward_passes set to 2 of a checkpoint written with 1 reports:
rs/output/./policy: configuration validation error: resume needs the forward-pass count the checkpoint was written with: training.selection.forward_passes is 2 here and 1 in the checkpoint; set it to 1 or continue with policy.mode = warm_startPython class: PolicyIncompatibleError, with the message prefix policy validation error: .
Resolution: Follow the way out the message names, or continue with policy.mode = "warm_start".
Stored trial-state refusals
Seção intitulada “Stored trial-state refusals”When it occurs: A full-FCF load reads a states/<pool>.bin file that does not fit the loaded pools: a
pool the study does not have, a state length that differs from the pool’s, or a state stored at a slot that
holds no loaded cut.
pool {pool}: stored trial states for a pool the study does not havepool {pool}: stored trial states have {n} values, the study's pool {dimension}pool {pool}: a trial state is stored at slot {slot}, which holds no cutResolution: Load a checkpoint written for the current study, or train a new policy.
Simulation cut-set refusal
Seção intitulada “Simulation cut-set refusal”When it occurs: A run with the dynamic method that simulates under simulation.cut_set = "all" loads a
policy, or policy.boundary rows, holding a row that "all" includes and that is not active
(Configuration — Simulation cut set).
training.cut_selection.selection.method = dynamic cannot simulate simulation.cut_set = all over this policy: {pool} holds {held} cuts of which {active} are active (it was written by a run that deactivates cuts), and a dynamic lazy solve reads only the active cuts; set simulation.cut_set = active or use the level1 method{pool} is pool {id} for the first such pool of the loaded policy, or the policy.boundary pool for the boundary rows.
Resolution: Set simulation.cut_set to "active", or use the level1 method.
Boundary inflow-lag mismatch
Seção intitulada “Boundary inflow-lag mismatch”When it occurs: A boundary load (policy.boundary) finds an inflow-lag slot of the current study that the boundary checkpoint cannot supply. Either the checkpoint prices no inflow-lag coefficient for a hydro at a lag depth the study needs, or the coefficient it holds references a different past than the study: both sides carry a reference date and the two dates differ. Compatibility requirements gives the order of the boundary checks.
Messages:
No coefficient for a hydro at a lag depth; {names} lists every missing pair as hydro {id} at lag depth {depth}, separated by commas:
boundary policy has no inflow-lag coefficient for {names}: the boundary is lag-depth-incompatible with the current studyA coefficient that references a different past; the two dates print as YYYY-MM-DD:
boundary policy's inflow-lag coefficient for hydro {id} at lag depth {depth} references a different past than the current study: boundary {date}, current {date}Python class: Python raises ValidationError with the message prefix boundary cut error: . novomodelo validate labels the message policy.boundary: .
Resolution: If the checkpoint has no coefficient for a hydro at a lag depth, train the source checkpoint with inflow_lags: true on the stage that follows the source pool’s stage. If the two dates differ, give the source pool’s stage and the study’s last stage the same start date, and do the same for each earlier pair of stages; Compatibility requirements describes both conditions.
Solver profile validation
Seção intitulada “Solver profile validation”Per-phase solver-profile overrides (training.solver.backward,
training.solver.forward, simulation.solver) are validated against the
compiled backend’s support matrix at study setup, before any stage LP is
built, on every MPI process; every rejection below is a configuration error with its
own message.
novomodelo validate runs these checks on every case: it reports a rejection with phase
StudySetupError (config.json: configuration validation error: …), or
BoundaryReconciliationError with policy.boundary configured.
novomodelo run refuses the case before training. Both exit 1.
CLP backend: every override is rejected
Seção intitulada “CLP backend: every override is rejected”When it occurs: A binary built with the CLP backend (see
Installation — CLP build)
rejects every solver-profile override field outright — CLP’s own option
surface has not been measured against these fields, so novomodelo refuses to
silently apply a HiGHS-flavored value to it. An empty "solver": {} block and
an absent solver block are both legal; only a field that is actually set
triggers the error. When a profile sets more than one field, only the first
field in declaration order is named, so fixing one field at a time surfaces
one error per fix cycle rather than a combined report.
Example:
solver profile field "dual_edge_weight" for phase "backward" is unsupported on backend "clp": rejected until CLP is re-measuredFor primal_feasibility_tolerance, the field token additionally carries the
value that was set:
solver profile field "primal_feasibility_tolerance" (1e-7) for phase "forward" is unsupported on backend "clp": rejected until CLP is re-measured"<phase>" is one of forward, backward, or simulation.
Resolution: Remove the override field from config.json on a CLP-built
binary, or switch to the default HiGHS backend if the override is required.
HiGHS backend: six per-field range checks
Seção intitulada “HiGHS backend: six per-field range checks”The default (highs) backend accepts every solver-profile field. The closed
enums (dual_edge_weight, scale, price, presolve) and use_warm_start
are unconditionally valid — every variant is checked when config.json is
read, so there is no separate runtime range check for them. The remaining
six numeric fields are range-checked at study setup; each failure names the
field, the rejected value, and the phase (forward / backward /
simulation) whose profile set it.
| Field | Rule | Message |
|---|---|---|
primal_feasibility_tolerance | must be finite | unsupported primal_feasibility_tolerance {value} for backend "highs" in phase "{phase}": value must be finite |
dual_feasibility_tolerance | must be finite and >= 0.0000000001 | unsupported dual_feasibility_tolerance {value} for backend "highs" in phase "{phase}": value must be finite and >= 0.0000000001 |
simplex_update_limit | must be <= 2147483647 | unsupported simplex_update_limit {value} for backend "highs" in phase "{phase}": value must be <= 2147483647 |
cost_perturbation | must be finite and >= 0 | unsupported cost_perturbation {value} for backend "highs" in phase "{phase}": value must be finite and >= 0 |
factor_pivot_threshold | must be in [0.0008, 0.5] | unsupported factor_pivot_threshold {value} for backend "highs" in phase "{phase}": value must be in [0.0008, 0.5] |
steepest_edge_devex_fallback_threshold | must be finite and >= 1.0 | unsupported steepest_edge_devex_fallback_threshold {value} for backend "highs" in phase "{phase}": value must be finite and >= 1.0 |
0.0000000001 is 1e-10 printed in full; 2147483647 is the largest 32-bit
signed integer; [0.0008, 0.5] is HiGHS’s own accepted pivot-threshold range.
Resolution: Adjust the offending field to satisfy the rule in the table.
{phase} in the message identifies which of training.solver.backward,
training.solver.forward, or simulation.solver set the invalid value.
Runtime errors
Seção intitulada “Runtime errors”A failure during novomodelo run prints error: {message} on stderr, followed by hint lines that depend on the exit code:
- Exit
1, a refusal met during the run (for example a--threadsmismatch), adds-> run `novomodelo validate <CASE_DIR>` for a full diagnostic report. - Exit
2, whose message isI/O error in {context}: {source}, adds-> check that the path exists and you have read/write permissions. - Exit
3adds-> check constraint bounds (hydros may have conflicting min/max storage)and-> run `novomodelo validate <CASE_DIR>` for a full diagnostic report. - Exit
4adds-> this may indicate a software or environment problemand-> report this at https://github.com/ons-ccee-epe/novomodelo/issues.
On two or more MPI processes, each failing process (an MPI rank) first prints rank {rank}: on its own line and then the same lines, and the job stops with that process’s exit code. When rank 0 fails to write the run outputs, every rank exits with rank 0’s code, and the others print rank 0 failed to write the run outputs; failing on every rank in lockstep. A checkpoint that does not fit the study is refused before training or simulation starts; see Policy-load errors.
A panic, an internal fault, prints its message on stderr and exits 101. On two or more MPI processes, the process that panics then prints rank {rank}: panicked; aborting the MPI job and aborts the whole job with exit code 101.
Solver failures
Seção intitulada “Solver failures”A failure inside a training iteration ends training and exits with the code of its error: 3 for an LP or solver failure, 4 for a communication failure, 1 for a refusal. A run without --quiet first prints Training failed after {n} iterations. Partial outputs written to {dir}; the partial policy is in {policy}. on stderr, where {policy} is the policy directory with .partial appended: a failed run writes its partial policy beside policy.path and never replaces a checkpoint at policy.path. The run also logs ERROR training failed after {n} iterations: {error} on stderr, with --quiet as well. Under MPI, a process that fails first can abort the job before the root process prints these lines. The same LP failures in simulation exit 3; see Simulation failures.
| Message | Exit code | When it occurs | Resolution |
|---|---|---|---|
LP infeasible at stage {stage}, iteration {iteration}, scenario {scenario} | 3 | A stage LP of a training iteration has no feasible solution; {stage} and {scenario} are 0-based positions. | Check the constraint bounds at that stage, such as a generic constraint whose slack is disabled or conflicting hydro bounds; novomodelo validate does not solve the stage LPs, so it can accept such a case. |
{solver_message} | 3 | A stage LP of a training iteration ends in a solver failure other than infeasibility; {solver_message} is one of the solver messages below, for example LP is unbounded. | Look up {solver_message} in the rows below. |
LP is unbounded | 3 | The objective of the stage LP is unbounded below. | Look for a missing bound or a cost with the wrong sign in the case. |
numerical difficulty: {message} | 3 | The solver reports numerical difficulties that persist through all its retries; {message} is the solver’s description. | Report the case with the message. |
time limit exceeded after {seconds}s or iteration limit reached after {iterations} iterations | 3 | A single LP solve ends at its time budget or at the solver’s simplex iteration limit. | Report the case with the message. |
internal solver error (code {code}): {message} or internal solver error: {message} | 3 | The solver fails in a way it cannot classify. | Report the case with the message. |
basis inconsistent: num_row={num_row}, total_basic={total_basic} (col_basic={col_basic}, row_basic={row_basic}) or basis row count mismatch: lp_rows={lp_rows}, basis_rows={basis_rows} | 3 | The solver rejects a warm-start basis that does not fit the LP. | Report the case with the message. |
non-uniform n_workers_local across MPI ranks: local={local}, min={min}, max={max}; all ranks must run with the same --threads value | 1 | The MPI processes of one job started with different --threads values, and the backward pass of the first iteration detects it; local is the printing process’s thread count, and min and max are the smallest and largest counts. | Start every process of the job with the same --threads value. |
{solver} initialisation failed: {e} | 3 | The solver backend (HiGHS or CLP) cannot create its solver instance when training starts; {e} is the backend’s message. | Report it with the full message. |
{solver} initialisation failed for simulation pool: {e} | 3 | The solver backend cannot create the solver instances of the simulation workers. | Report it with the full message. |
An infeasible stage LP in the first training iteration of a single-process run, on a case that novomodelo validate accepts, prints:
ERROR training failed after 0 iterations: infeasible subproblem at stage 0, iteration 1, scenario 0Training failed after 0 iterations. Partial outputs written to ./out; the partial policy is in ./out/policy.partial.error: LP infeasible at stage 0, iteration 1, scenario 0 -> check constraint bounds (hydros may have conflicting min/max storage) -> run `novomodelo validate <CASE_DIR>` for a full diagnostic reportSolves that miss a row bound
Seção intitulada “Solves that miss a row bound”When any LP solve of the run returned an optimal primal solution that misses a
row bound, novomodelo run prints one line on stderr when the run ends (rank 0
only; --quiet does not suppress it). The run still succeeds and the exit code
does not change:
warning: LP solves returned a primal solution that misses a row bound by more than the primal feasibility tolerance plus 1e-11 of the row's magnitude: {n} of {m} (forward {f}, backward {b}, lower bound {l}, simulation {s}); per-stage counts are in the lp_row_violations column of solver/iterations.parquetA row counts when its violation exceeds the solver’s primal feasibility
tolerance plus 1e-11 times the row’s magnitude: the sum of the absolute values
of its terms at the returned solution, taken as at least 1. The Python
novomodelo.run prints the same text prefixed by novomodelo-python: . A count
above zero means outputs recomputed from that solve (balances, duals, cuts) may
not close; report it with the case.
Simulation failures
Seção intitulada “Simulation failures”A stage-LP failure in simulation exits 3, and every other simulation failure exits 4.
| Message | Exit code | When it occurs | Resolution |
|---|---|---|---|
LP infeasible at scenario {scenario_id}, stage {stage_id}: {solver_message} | 3 | A stage LP of a simulation scenario has no feasible solution; {solver_message} reads LP infeasible. | Check the constraint bounds at that stage, such as a generic constraint whose slack is disabled; novomodelo validate does not solve the stage LPs, so it can accept such a case. |
solver error at scenario {scenario_id}, stage {stage_id}: {solver_message} | 3 | A stage LP of a simulation scenario ends in a solver failure other than infeasibility; {solver_message} is one of the solver messages of Solver failures. | Find the solver message in those rows. |
stochastic error: {detail} | 4 | The scenario sampler of the simulation cannot be built or fails to sample; {detail} is the stochastic model’s message. | See Stochastic failures during a run. |
invalid simulation configuration: {detail} | 4 | The simulation setup fails an internal consistency check. | Report the case with the message. |
simulation output channel closed unexpectedly or simulation drain thread panicked | 4 | The thread that writes the simulation results stops before the simulation ends. | Report the case with the full output of the run. |
simulation cost aggregation error: I/O error during simulation output: {message} | 4 | The gather of the per-scenario costs across the MPI processes fails at the end of the simulation; {message} names the gather, allgatherv(counts) or allgatherv(costs), and the communication error. This is a communication failure, not a filesystem error; it exits 4. | See Communication failures. |
a peer rank failed simulation; failing on every rank in lockstep | 4 | Another MPI process fails during the simulation, and this process stops with it. | Read the error printed under the rank {rank}: line of the process that failed first. |
Communication failures
Seção intitulada “Communication failures”| Message | Exit code | When it occurs | Resolution |
|---|---|---|---|
communication backend error: communication backend 'mpi' is not available in this build (available: local) | 4 | --comm-backend mpi is set on a binary built without MPI support, which offers only the local backend. | Run the novomodelo-mpi build under an MPI launcher (see HPC & Cluster Deployment), or drop --comm-backend mpi to run on one process. |
communication backend error: 'mpi' backend initialization failed: {source} | 4 | The MPI runtime fails to initialise in an MPI build; {source} carries the MPI library’s message. | Check that the MPI runtime is installed and that the job starts under mpiexec, mpirun or srun. |
collective operation '{operation}' failed with MPI error code {code}: {message} | 4 | An MPI collective operation (broadcast, barrier, allreduce or allgatherv) fails during the run. The text follows a label that names the step, such as broadcast error (data): , post-training barrier error: or simulation path gather error: . | Read the MPI library’s message and the output of the other processes to find the process that failed first. |
cut_wire: unsupported version {version} | 1 | In the backward pass of a training iteration, a process reads a cut record whose version byte is not the one its own binary writes, which happens when the processes of one job run builds with different cut wire-format versions. {version} is the byte the sending process wrote. The message adds the validate hint. | Restart every process with the same novomodelo binary. |
try_from_broadcast_payload: unsupported wire version {version} at stage {stage} (expected {expected}) | 1 | A process reads stored LP bases that another process wrote with a wire-format version other than its own: rank 0 when it gathers the bases of every process at a periodic checkpoint and at the end of training, and every other process when it reads the warm-start bases that rank 0 broadcasts at the end of training. {version} is the version the sending process wrote and {stage} the 0-based node position. The novomodelo validate hint after it does not apply. | Restart every process with the same novomodelo binary. |
gather_basis_store: rank {rank} sent more than its {passes} rows at node {node} or gather_basis_store: rank {rank}'s basis payload at node {node} does not fit an i32 count | 1 | Rank 0 cannot decode the stored LP bases it gathers from every process at a periodic checkpoint or at the end of training, or the bases one process holds for a node exceed an MPI count. The novomodelo validate hint after it does not apply. | Report the case with the message. |
rank 0 signaled broadcast failure (length 0) | 4 | Rank 0 fails while loading the case, before it broadcasts the study, so the other processes receive an empty broadcast; rank 0 exits with the code of its own error. | Fix the error that rank 0 prints under its rank 0: line. |
hydro model preprocessing error on non-root rank: {e} | 4 | A process other than rank 0 fails to prepare the hydro models, which it rebuilds from the case directory. | Give every process read access to the same case directory, and read {e} for the cause. |
opening tree differs across MPI ranks (fingerprints {min:#018x} to {max:#018x}); every rank must build the same tree from the broadcast inputs | 4 | On two or more MPI processes, the digests of the opening tree that the ranks built differ after setup, so they would train against different trees; {min} and {max} are the smallest and the largest digest, each 0x and 16 hexadecimal digits (Opening tree across MPI ranks). | Report the case with the message. |
opening tree fingerprint exchange failed: {e} | 4 | The exchange of the opening-tree digests across the MPI processes fails; {e} is the communication error. | Read {e} for the failing operation. |
enumerated training at world >= 2 requires a graph with no interior branching (a deterministic trunk + terminal fan): node {node_id} is a non-leaf node not shared by every root→leaf path — the enumerated forward's per-rank state exchange is elided for it, so the replicated backward would cut against a zeroed incoming state on any rank that never visits it, pending the interior-node state-exchange fix | 1 | Enumerated training (training.selection.method "enumerated") runs on two or more MPI processes over a policy graph with an interior branching node; the message has no prefix and is followed by -> run `novomodelo validate <CASE_DIR>` for a full diagnostic report, although novomodelo validate does not check this and exits 0 on the case. | Keep all branching at the last stage, run on one process, or use sampled selection. |
Requesting the MPI backend from a binary built without MPI support prints:
error: communication backend error: communication backend 'mpi' is not available in this build (available: local) -> this may indicate a software or environment problem -> report this at https://github.com/ons-ccee-epe/novomodelo/issuesOutput-writing failures
Seção intitulada “Output-writing failures”A filesystem failure while writing the policy checkpoint or the training and simulation results exits 2, except the write of one simulation scenario’s results, which the last row describes. The training/ files written before training starts exit 4 on any failure, so an unwritable --output directory ends with exit 4 unless removing a stale output fails first, which exits 2.
| Message | Exit code | When it occurs | Resolution |
|---|---|---|---|
I/O error in {context}: {source} | 2 | A write of the policy checkpoint or of training or simulation results after training starts fails on the filesystem, for example when the disk is full or a results file cannot be created; {context} is the path. | Check that {context} exists and is writable and that the disk has free space, then rerun. |
I/O error in checkpoint write at iteration {n}: {path}: {source} | 2 | A periodic checkpoint cannot be written to policy.path. | Check that the policy directory is writable and the disk has space. |
checkpoint write at iteration {n}: refusing to write a checkpoint: {entry}, found in {dir}, is not part of a checkpoint (manifest.bin, metadata.json, cuts/, basis/, states/); move it elsewhere or write the checkpoint to another directory | 1 | The policy directory holds an entry no checkpoint writer leaves there; nothing on disk changes. | Move the entry, or set policy.path to another directory. |
checkpoint write at iteration {n}: {e} | 4 | Encoding a periodic checkpoint fails; {e} is the encoder’s message. | Report the case with the message. |
I/O error in {path}: {source} | 2 | A stale output in --output, such as a _SUCCESS marker, cannot be removed before training starts; {path} is the entry. | Make the entry removable, or point --output at a directory without it. |
failed to write hydro model summary: {e}, failed to write provenance report: {e} or failed to write scaling report: {e} | 4 | One of the training/ files that novomodelo run writes before training starts cannot be written; {e} is the writer’s message, for example I/O error accessing {path}: {source}. | Point --output at a directory the process can create and write. |
rank 0 pre-training export failed; failing on every rank in lockstep | 4 | On MPI, rank 0 fails one of those writes or removals, and every other process prints this message. | Fix the error that rank 0 prints under its rank 0: line. |
serialization error for entity {entity}: {message} | 4 | Encoding an output table fails for the named entity collection, or a policy checkpoint write refuses its payloads before anything is written: {entity} is then policy_checkpoint_structure, policy_checkpoint_dates or policy_checkpoint_size, and {message} names the file and the rule it breaks (Checkpoint Directory Contents). | Report the case with the message. |
manifest error for {manifest_type}: {message} | 4 | Building an output manifest fails. | Report the case with the message. |
ERROR simulation write error: {e} | 0 | The results of one simulation scenario cannot be written. The run continues and exits 0, and scenarios.failed in simulation/metadata.json counts the failed scenarios. | Fix the cause named in {e}, rerun the simulation, and check scenarios.failed after every run. |
Stochastic failures during a run
Seção intitulada “Stochastic failures during a run”A stochastic-model refusal raised while the study is set up exits 1 in both commands; StochasticPreparationError quotes it. The simulation sampler’s stochastic error: … exits 4 (Simulation failures).