Each table maps a failure you see to its cause and to the change that clears it. The exact message text lives on Error Codes, and the exit codes on CLI Reference; every row links the entry that owns its message.
| Symptom | Cause | Fix |
|---|
unknown field in config.json; exit 1; message | config.json holds a key that the object around it does not accept, such as a misspelt name or a field that belongs to another stopping-rule type. | Remove or correct the key against Configuration. The message gives the line and column. |
a forward-pass count is required; exit 1; message | training.selection is absent. The key is required even when training.enabled is false. | Add training.selection; see training.selection. |
required field is missing on training.stopping_rules; exit 1; message | training.stopping_rules is absent. The key is required even when training.enabled is false. | Add a rule set that holds an iteration_limit rule; see training. |
unsupported factor_pivot_threshold (or another solver-profile field); exit 1; message | A per-phase override (training.solver.backward, training.solver.forward or simulation.solver) is checked against the compiled solver backend when the study is built. Both novomodelo validate and novomodelo run report the rejection. A CLP build refuses every override. | Set the field within the range the message names, or remove the override; see training.solver. |
Admission rules for the scenario_source blocks report one failure at a time, in code order, so fixing one message can reveal the next: rerun novomodelo validate until it passes. The rules check simulation.scenario_source as well as training.scenario_source, and they check it even when simulation.enabled is false. The rule table is in Scenario-source admission rules.
| Symptom | Cause | Fix |
|---|
policy was written by; exit 1; Error Codes — PolicySoftwareMismatch | The checkpoint’s manifest.bin records another software or version than the running one. The comparison is exact. | Re-run the program that produced the checkpoint with the running version; for a converted boundary policy, convert it again; see Version gate. |
Policy directory not found; exit 1; message | No checkpoint exists at policy.path, resolved against the output directory. A first run killed before it wrote any checkpoint leaves none. | Point policy.path at the checkpoint, or train first; see Policy Load Contract. |
failed to read policy checkpoint; exit 1 (2 with I/O error in … for a file the OS refuses to read); message | The checkpoint at policy.path cannot be read, for example one whose format_version is not 3 (unsupported checkpoint manifest format_version …), or the directory exists and neither it nor its .staging and .previous siblings hold a manifest.bin. An interrupted write that replaces a checkpoint leaves a complete one, old or new. | Re-run the program that produced the checkpoint with the running version, or point policy.path at a complete checkpoint; see Checkpoint Directory Contents. |
novomodelo validate runs the same load (--output names another output directory), so both commands meet these refusals. Both commands read a policy.boundary checkpoint.
| Symptom | Cause | Fix |
|---|
LP infeasible at scenario; exit 3; message | A stage LP of a simulation scenario has no feasible solution. novomodelo validate does not solve stage LPs, so it accepts such a case. | Read the scenario and stage in the message, then check the constraint bounds at that stage, such as hydro minimum and maximum storage that conflict. Penalty System lists which constraints are soft. |
Training failed after; exit 3 (4 for a communication failure); message | A stage LP of a training iteration failed, for example an infeasible subproblem. Training stops and writes partial outputs to the output directory. | For an infeasible subproblem, the error: LP infeasible at stage … line names the stage, iteration and scenario (stage and scenario are 0-based); check the constraint bounds at that stage. Penalty System lists which constraints are soft. A solver failure prints the solver message, which the linked entry lists. |
| Symptom | Cause | Fix |
|---|
The Execution banner prints once per rank, and its line Layout: {world_size} {rank_word} on <host> reads 1 rank; diagnosis | The processes did not form one MPI job: each initialised MPI as its own one-rank job. | Follow the diagnosis and rebuild steps in HPC & Cluster Deployment. |
pmijobid missing in fullinit command; diagnosis | An MPICH built for PMIx has no PMI-2 client, so srun --mpi=pmi2 cannot launch it. An incompatibility between SLURM’s PMI2 plugin and MPICH’s PMI2 wire protocol gives the same error. | Launch with srun --mpi=pmix; see HPC & Cluster Deployment. |
same --threads value; exit 1; message | The ranks of one job started with different --threads values, and the backward pass detects it. | Start every rank with the same --threads value. |
'mpi' is not available in this build; exit 4; message | --comm-backend mpi is set on a binary built without MPI support; novomodelo version prints comm: local. | Run the novomodelo-mpi binary under an MPI launcher; see HPC & Cluster Deployment. |
novomodelo validate reports the first three rows as StochasticPreparationError for the opening-tree library and as StudySetupError for the forward historical scheme’s library (BoundaryReconciliationError with policy.boundary); Historical-library refusals quotes them.
| Symptom | Cause | Fix |
|---|
V2.1: stage; exit 1; message | A study stage has no season_id: it declares none, and the season definitions are absent or leave its start date uncovered. | Assign a season_id to every study stage. |
V2.3, non-finite eta; exit 1; message | A hydro has a zero seasonal standard deviation and a historical observation that differs from its mean, or the fit fails numerically. | Supply history equal to the hydro’s mean, or a non-zero standard deviation. |
no valid historical windows found; exit 1; message | No start year has history that covers the required seasons, so the window pool is empty. | Supply history that covers the required seasons for at least one start year. |
openings source is 'file'; exit 2; message | training.scenario_source.openings is {"source": "file"} and scenarios/noise_openings.parquet is absent. | Place the tree at scenarios/noise_openings.parquet, or declare {"source": "generated"} or no openings so Novomodelo generates it; see training. |