Warnings
A fit collects non-fatal issues into two parallel channels on FitResult:
warnings— aVec<String>of human-readable messages, shown by the CLI and written to the YAML /.fitrxbundle. This is the display channel.warnings_structured— aVec<WarningEntry>, the machine-branchable channel. Each entry carries a typedWarningCode, a severity, the message, an optional originating method, and an optional numericdetailspayload. This is what a script, the R wrapper, or an agentic model-development loop should read — it is serialized in the JSON output.
{
"severity": "Warning",
"category": "dw_autocorrelation",
"message": "Positive IWRES autocorrelation detected (Durbin-Watson = 1.20).",
"source_method": null
}category is the stable snake_case token of a WarningCode. It is a public API surface: tokens never change or get repurposed once released, so a consumer can branch on them safely (new warning classes get new tokens). details is omitted when empty.
Which entry points report warnings
fit() is not the only door. Every model/data finding and every ODE-solver diagnostic is reported by each entry point that has a channel to carry it, and the list is the same one on all of them, with one exception. simulate_adaptive() does not report W_NO_DOSES: its controller supplies the regimen, so a dataset with no dose records is the expected input there, and the warning’s advice (check for an AMT column with dose rows) does not apply.
| Entry point | Channel | Carries |
|---|---|---|
fit() |
FitResult::warnings / warnings_structured |
everything below, plus the fit-only codes: convergence, covariance, shrinkage, the estimator/optimizer option warnings and the packed-start rails |
ferx check |
the check report | everything below except the solver diagnostics (nothing has been integrated yet), plus the option warnings |
predict_diag() |
PredictionOutput::warnings |
the non-fit bundle (below) |
predict_survival_diag() |
SurvivalPredictionOutput::warnings |
the non-fit bundle; its solver diagnostics are those of an ODE-accumulated (joint PK-TTE) hazard’s integration |
simulate_with_options_diag() |
SimulationOutput::warnings |
the same, plus per-subject simulation diagnostics and one W_SIMULATED_FLIP_FLOP count of the simulated individuals dosed before one of their observations whose sampled η crossed into a twin-less closed form’s flip-flop regime, so none of their rows carries any contribution from the doses the subject was given. Those rows are not necessarily ipred == 0.0, so the count is the only reliable way to find them |
compute_npde_npd_diag() |
its returned Vec<String> |
W_IOV_NO_OCCASIONS, and one W_SIMULATED_FLIP_FLOP count of the NPDE/NPD reference replicates whose sampled η crossed into a twin-less closed form’s flip-flop regime, so the reference they are scored against carries undosed profiles (#1928). fit()’s post-fit NPDE step forwards that count to FitResult::warnings |
compute_tte_npde() |
its returned Vec<String> |
the simulator’s warnings for the reference replicates, one per warning code with the number raised (a degenerate hazard draw, a failed event-time solve). A fit with npde_nsim > 0 keeps only W_TTE_SOLVE_FAILED, worded as reference replicates, and reports an input it cannot score as W_NPDE_TTE_SKIPPED |
simulate_with_uncertainty_diag() |
SimulationOutput::warnings |
the same, plus one W_UNCERTAINTY_DRAWS_SKIPPED warning naming every parameter draw skipped in the flip-flop regime. Both warnings can fire on one run: a skip is a θ the closed form cannot serve at all, the count is an η inside a draw that ran |
simulate_adaptive() |
AdaptiveSimulationResult::warnings |
the non-fit bundle, except W_NO_DOSES |
predict(), predict_survival(), simulate(), simulate_with_seed(), simulate_with_options(), simulate_with_uncertainty() |
— | nothing; each is a thin wrapper over its _diag form above |
predict_categorical() |
— | nothing yet |
simulate_with_uncertainty_diag() is newer than 0.4.0 (#1645), and so is predict_survival_diag() (#2164). Before ferx 0.4.0 predict_diag(), simulate_with_options_diag() and simulate_adaptive() were silent. That mattered because the failures they were silent about are the ones that look fine: an SS=1 dose on an [odes] right-hand side reading TAFD came back through predict() as a column of NaN with no explanation, and a segment that exhausted ode_max_steps came back as a column of identical finite numbers — plottable, and wrong.
When a precondition fails
A warning is a finding the run survives. A precondition is one it does not: a dose into a compartment the model cannot deliver into, a coded RATE with no D{n} / R{n} parameter behind it, a covariate the data does not carry, a time-varying covariate on a hazard, an absorption form the closed form cannot honour. fit() has always returned these as an Err. Since ferx 0.4.0 every other entry point does too — for the preconditions it checks, which is not the same list on each:
| Entry point | Preconditions it checks, in the order it runs them |
|---|---|
fit(), ferx check |
every item below that is about the model or the data. Not the simulate-only ones (TTE simulatable, ΩIOV in the supplied parameters, horizon), and not the CTMM ones: fit() supports a [markov_model] endpoint — it is prediction and simulation that have no CTMM path yet. |
predict_diag() |
coded RATE, θ levels bound, θ length, population bound for the θ levels, covariates present, endpoint routing, [covariate_model] bound, covariate levels, dose compartment, absorption closed-form support, flip-flop without an ODE twin, time-varying covariate on a hazard, unsupported depot readout, absorption input rate, a CTMM-only model |
simulate_with_options(), simulate_with_options_diag() |
TTE simulatable (finite horizon, no resets), ΩIOV present, the simulation data checks (θ levels and [covariate_model] bound, covariate levels, population bound for the θ levels, covariates present, endpoint routing, κ weights, residual weights), a valid horizon, then θ length, coded RATE, dose compartment, absorption closed-form support, flip-flop without an ODE twin, time-varying covariate on a hazard, unsupported depot readout, absorption input rate, a CTMM model. |
simulate_with_uncertainty(), simulate_with_uncertainty_diag() |
θ length, TTE simulatable (finite horizon, no resets), the simulation data checks (the list in the row above), a valid horizon, flip-flop without an ODE twin at the point estimate; then per parameter draw: flip-flop without an ODE twin — which here skips the draw rather than refusing the run (see the exception below) — coded RATE, dose compartment, absorption closed-form support, time-varying covariate on a hazard, unsupported depot readout, absorption input rate, a CTMM model, ΩIOV present. |
predict_survival(), predict_survival_diag() |
time-varying covariate on a hazard, θ levels bound, θ length, population bound for the θ levels, covariates present, dose compartment, covariate levels |
predict_categorical() |
time-varying covariate on the linear predictor, θ levels bound, θ length, population bound for the θ levels, covariates present, endpoint routing, covariate levels |
inits_from_nca() |
coded RATE, dose compartment |
simulate_adaptive(), simulate_adaptive_from_spec() |
an ODE model, the simulation data checks (θ levels and [covariate_model] bound, covariate levels, population bound for the θ levels, covariates present, endpoint routing, κ weights, residual weights), a covariate-selected [error_model], a residual-error magnitude, θ length, then its other adaptive-dosing rejections (simulate_adaptive_from_spec() first refuses an opts that sets decision_times or monitors), then coded RATE, dose compartment, absorption closed-form support, absorption input rate. Not the time-varying covariate on a hazard, and not the flip-flop check. |
predict() |
predict_diag()’s list, in its order. |
simulate(), simulate_with_seed() |
the same set as simulate_with_options() bar horizon, which they do not take, in a different order — θ length, coded RATE, dose compartment, absorption closed-form support, flip-flop without an ODE twin, time-varying covariate on a hazard, absorption input rate, a CTMM model, TTE simulatable, ΩIOV present, the simulation data checks. |
A precondition an entry point does not check is not refused by it: the call returns rows computed from an input fit() would have rejected. Validate a new model and dataset with fit() or ferx check first.
The message is the one fit() gives for that precondition — the subject, the time and the remedy, with nothing wrapped around them. When an input fails several preconditions at once, each entry point reports the first one in its own check order, and the orders differ, so two entry points can name two different (both real) defects for the same input.
Before 0.4.0 predict(), simulate(), simulate_with_seed(), predict_survival(), predict_categorical() and inits_from_nca() returned bare values and panicked, and the three simulate_with_* forms panicked out of a function that returns Result, so a caller matching on Err never saw the failure. The panic text also carried a wrapper sentence around the diagnostic; that wording is gone.
“Covariates present” is model-wide
On every entry point, “covariates present” asks for every covariate the model reads, including one only another endpoint reads. So the selector of a covariate-selected [error_model] is required by predict_survival() and predict_categorical() too, though neither reads the Gaussian residual (#1798).
A skipped draw is not a refusal
One deliberate exception: inside simulate_with_uncertainty(), a parameter draw that lands in a twin-less transit or IG model’s flip-flop regime is skipped and the run continues. The point estimate is checked first and refused with the same code simulate() gives, so the skip only ever drops draws around an in-domain estimate. A run in which every draw is skipped is refused as well, with E_TRANSIT_FLIP_FLOP (E_IG_FLIP_FLOP).
A surviving draw is not automatically clean, because the skip is decided at the draw’s typical (η = 0) parameters: an individual inside it whose own sampled η crosses the abscissa has its entire dose-driven concentration clamped to zero, and those are counted separately in W_SIMULATED_FLIP_FLOP (flip_flop, #1823). Whether such a row reads as a literal zero depends on the values the model’s own expressions produce after the clamp, so looking for a zero will not find them. See Individuals in the flip-flop regime.
Otherwise the skips are reported as one uncertainty_draws_skipped warning: how many of the requested draws were dropped, and which. The dropped draws are not a random subset — they are the tail in which elimination is at least as fast as absorption — so intervals built from the rest are biased, not just wider. An explicit ODE transit() / igd() model simulates every draw.
Matching on the code
Every entry point in the table above returns its Err as an EngineError rather than a String, and so do the file entry points built on fit() (fit_from_files, prepare_run, run_model_with_data, run_model_simulate and their variants). Its to_string() is the message described above, unchanged, so code that only prints or searches the text calls .to_string() and keeps working.
When ferx check reports the same refusal with a code, the EngineError carries that diagnostic: code(), block() and suggestion() return what the check report gives for the same model and data. A caller can match on code() instead of parsing the message. message() never repeats the suggestion, so show either to_string() alone or message() with suggestion() beside it. (predict()’s refusal of an unbound theta NAME[...] block and E_LOGIT_THETA_OUT_OF_RANGE also end their to_string() with the suggestion.) A refusal ferx check cannot reach has a code too, since it has no parameter vector, no fit, no simulation options and no adaptive controller: the θ length and parameter shape codes, the binding codes on a fit’s bindings, a population that is not the fit’s (E_POPULATION_MISMATCH), and the simulation, adaptive-dosing and post-hoc codes the check report lists on their own. code() is None only for a failure that is not a refusal of the input, such as a posthoc eta that does not converge, a SIR run whose every draw is invalid, or an adaptive-dosing run whose frozen-schedule replay disagrees with it.
Codes by precondition
Each precondition check emits one of a fixed set of codes, depending on what it found:
| Precondition | code() |
|---|---|
coded RATE |
E_MODELED_RATE_NO_PARAM, E_MODELED_DURATION_NO_PARAM, E_DOSE_ATTR_DOUBLE_USE |
| covariates present | E_MISSING_COVARIATE, E_ETA_NOT_DECLARED |
[covariate_model] bound |
E_COVSTAT_UNRESOLVED |
| covariate levels | E_COV_LEVEL_UNKNOWN |
| θ levels bound, population bound for the θ levels | E_THETA_LEVELS_UNBOUND, E_THETA_LEVELS_DATA_UNBOUND, E_THETA_LEVELS_DATA_MISMATCH; the simulation data checks also E_THETA_GATHER_INDEX_MISSING, E_THETA_GATHER_INDEX_RANGE |
| θ length | E_THETA_LENGTH |
| Ω, σ, ΩIOV shape | E_PARAM_SHAPE |
| dose compartment | E_DOSE_CMT_OUT_OF_RANGE, E_DOSE_CMT_NOT_INFUSABLE |
| absorption closed-form support | E_TRANSIT_UNSUPPORTED (E_IG_UNSUPPORTED for an inverse-Gaussian model) |
| flip-flop without an ODE twin | E_TRANSIT_FLIP_FLOP (E_IG_FLIP_FLOP) |
| absorption input rate | E_ABSORPTION_FRACTION, E_ABSORPTION_DOMAIN, E_ABSORPTION_DIFFUSION, E_ABSORPTION_RATE_ZERO_ORDER, E_ABSORPTION_SS_INFUSION, E_ABSORPTION_SS_LAG, E_ABSORPTION_SS_ZERO_ORDER |
| κ weights, residual weights | E_KAPPA_WEIGHT_NONPOSITIVE, E_RUV_MAGNITUDE_NONPOSITIVE |
| endpoint routing | E_ENDPOINT_UNROUTED; on run_sir() / run_covariance() also E_ENDPOINT_NO_RECORDS |
| θ level binding, covariate statistics binding | E_THETA_LEVEL_BINDING, E_COVARIATE_STATS_BINDING |
population not the fit’s (run_sir(), run_covariance(), PopulationFingerprint::verify) |
E_POPULATION_MISMATCH; on run_sir() / run_covariance() also E_FIT_SUBJECTS_MISMATCH |
| time-varying covariate on an endpoint | E_ENDPOINT_TV_COVARIATE |
TIME-dependent disposition under a drug-driven hazard |
E_ENDPOINT_TIME_DEPENDENT_PK |
| unsupported depot readout | E_READOUT_DEPOT_UNSUPPORTED |
a CTMM model (predict*, simulate*) |
E_CTMM_UNSUPPORTED |
| TTE simulatable | E_TTE_NOT_SIMULATABLE, E_SIMULATE_HORIZON |
ΩIOV present (simulate*) |
E_PARAM_SHAPE |
SimulateOptions.horizon, SimulateUncertaintyOptions.horizon |
E_SIMULATE_HORIZON |
| propensity-score matching inputs | E_PROPENSITY_INPUT |
| adaptive dosing: the model, the options, the spec, a subject’s dose values, which subjects’ values a dose may read, the controller’s actions, supplied per-subject η | E_ADAPTIVE_UNSUPPORTED, E_ADAPTIVE_OPTIONS, E_ADAPTIVE_SPEC, E_ADAPTIVE_DOSE_VALUE, E_ADAPTIVE_DOSE_KNOWLEDGE, E_ADAPTIVE_CONTROLLER_ACTION, E_SUPPLIED_ETAS; an observe or dose-expression covariate the data lack, E_MISSING_COVARIATE |
individual survival curves (predict_survival_at_etas_diag): supplied per-subject η on a [mixture] model, with the wrong names, or missing for a subject |
E_SUPPLIED_ETAS |
a fit’s inputs (run_sir(), run_covariance()): missing, changed since the fit, a model that is not the fit’s |
E_FIT_INPUT_MISSING, E_FIT_INPUT_CHANGED, E_FIT_INPUT_MODEL; the fit’s θ count, E_THETA_LENGTH; a [mixture] fit’s override values (also simulate_with_uncertainty()), E_FIT_INPUT_MISSING or E_FIT_INPUT_MODEL |
the covariance matrix or SIR resamples to draw from (simulate_with_uncertainty()): not on the fit, or an empty pool; not the size of the model’s packed parameters |
E_FIT_INPUT_MISSING; E_FIT_INPUT_MODEL |
SIR settings (run_sir()) |
E_SIR_OPTIONS; a fit whose parameters are all FIX, E_SIR_NOTHING_TO_SAMPLE |
ODE solver settings on a FitOptions built in code (fit(), run_sir(), run_covariance()) |
E_ODE_SOLVER_OPTIONS |
a logit-scaled θ estimated outside (0, 1) (simulate_with_uncertainty() with the asymptotic method, run_sir()) |
E_LOGIT_THETA_OUT_OF_RANGE |
re-reading the fit’s model or data file (run_sir(), run_covariance()) |
what ferx check reports on the same file: E_MODEL_READ, the parse codes, E_DATA, E_MISSING_COVARIATE, E_COVARIATE_NOT_NUMERIC, E_PARSE |
fit() and the file entry points
fit()’s refusal of a model or data precondition carries the code in its row of the table above, as predict()’s does, and an unbound theta NAME[...] block is E_THETA_LEVELS_UNBOUND. On the file entry points the steps before the fit carry codes too: a model file that cannot be read or parsed, and a dataset that cannot be read, carry what ferx check reports on the same file, and the binders carry E_THETA_LEVEL_BINDING / E_COVARIATE_STATS_BINDING.
The refusals fit() used to raise without a code carry one since #1788, and ferx check reports each one it can reach, so the two do not disagree:
| Refusal | code() |
ferx check |
|---|---|---|
a [mixture] model: init_params with no per-class Ω/Σ |
E_PARAM_SHAPE |
— |
a [mixture] model: n_agq > 1, an estimator not wired for it, bayes with per-class overrides |
E_MIXTURE_METHOD |
yes |
| repeated-event records out of order, interval-censored, … | E_RTTE_RECORDS |
with --data |
| a binary DV outside {0, 1} | E_BINARY_STATE |
with --data |
| a CTMM state not declared, CTMM times out of order | E_CTMM_RECORDS |
with --data |
LTBS on a hand-built model with a proportional or (natural-scale) combined error on any endpoint, a covariate-selected error model or an SDE, or a LogCombined error without LTBS |
E_LTBS_UNSUPPORTED |
the parser refuses it first |
iiv_on_ruv: an η also used in [individual_parameters]; a non-interaction method |
E_IIV_ON_RUV_SHARED_ETA; E_IIV_ON_RUV_METHOD |
yes |
| the AGQ grid under IOV | E_AGQ_GRID_TOO_LARGE |
with --data |
a derived iov_occasion that gives one occasion per subject |
E_IOV_SINGLE_OCCASION |
with --data |
The file entry points add three: no data path and no [data] path (E_DATA_PATH_MISSING); on run_model_simulate(), no [simulation] block (E_MISSING_BLOCK), a design with nothing to observe (E_SIMULATION_DESIGN), a design missing a covariate the model reads (E_MISSING_COVARIATE), a TTE endpoint with no horizon (E_SIMULATE_HORIZON), a CTMM model (E_CTMM_UNSUPPORTED) and a derived iov_occasion that gives the template one occasion (E_IOV_SINGLE_OCCASION). Every message reads as before. code() is None only for a run that fails rather than a refused input: a cancelled fit, an estimator stage’s own failure, every start of a multi-start fit failing, or the simulation step of run_model_simulate() failing at run time.
run_sir() and run_covariance()
run_sir() and run_covariance() name themselves when they refuse the fit’s inputs — a changed model or data file, a population that is not the fit’s, a model that is not the fitted one, a categorical level the fit never saw: the EngineError’s context() is the entry point, to_string() starts with "run_sir: " / "run_covariance: ", and message() is the text without it. Their other refusals (dose compartment, endpoint routing, a fit with no covariance matrix) carry no context and no prefix, as before.
Of the input refusals, these carry a code:
- an unseen categorical level (
E_COV_LEVEL_UNKNOWN); - a supplied model whose
[covariate_model]is still unbound (E_COVSTAT_UNRESOLVED); - every refusal of the fit’s data bindings: a θ level the fit never estimated, malformed recorded bindings, and a fit that recorded none.
E_THETA_LEVEL_BINDINGon a model with a level block,E_COVARIATE_STATS_BINDINGon one with only[covariate_model]statistics; - a population that is not the one the fit was given (
E_POPULATION_MISMATCH): another subject list, other covariate columns, or a subject whose records, doses or covariate values differ.message()names what differs and how the population was obtained, andsuggestion()is the remedy. The same population gets the samemessage(),code()andsuggestion()fromPopulationFingerprint::verify(its own check); - the fit’s population, but per-subject results (
fit.subjects) in another count or order (E_FIT_SUBJECTS_MISMATCH). The two steps read those results by position, so the fit’s rows are what is wrong, not the population. A fit rebuilt from separate fields can get there; afit()result cannot; - an input neither passed nor recorded on the fit (
E_FIT_INPUT_MISSING): the model or data file’s path, SIR’s covariance matrix, the population of an IOV model passed in on a fit with no recorded reader settings, or the occasion rule of an IOV fit saved before ferx recorded one; - a model or data file whose SHA-256 is not the one the fit recorded (
E_FIT_INPUT_CHANGED); - a model that is not the fit’s (
E_FIT_INPUT_MODEL): one passed in with other data-derived bindings, or with covariate statistics the population does not reproduce, or one whose η count is not the width of the fit’s η̂; its θ count isE_THETA_LENGTHand its Ω, σ and ΩIOV shapeE_PARAM_SHAPE; - a
[mixture]fit’s per-class override values: not stored on the fit (E_FIT_INPUT_MISSING), or a packed estimate of another layout or one that no longer reproduces the reported estimates (E_FIT_INPUT_MODEL), and a SIR proposal that is not the size of the model’s packed parameters (E_FIT_INPUT_MODEL); - ODE solver settings on a
FitOptionsbuilt in code that no solver can run with (E_ODE_SOLVER_OPTIONS): anode_reltolorode_abstolthat is not finite and positive,ode_max_steps = 0, orode_stiff_abort_after = Some(0). A model file’s[fit_options]refuses the same values when it is parsed (E_PARSE); - a free θ used as
inv_logit(logit(θ) + ETA)whose estimate is not strictly inside (0, 1), sorun_sir()has no logit-scale proposal for it (E_LOGIT_THETA_OUT_OF_RANGE, on[parameters]). Only an upper bound above 1 lets the estimate get there;suggestion()says to declare one below 1 and refit.simulate_with_uncertainty()with the asymptotic method refuses it the same way; - SIR settings
run_sir()cannot run with (E_SIR_OPTIONS):sir_resamplesabovesir_samples, asir_dfbelow 1,sir_scale = naturalunder a prior.fit()refuses asir_dfbelow 1 up front when SIR can run (#1770), and withsir = truereports the other two as a warning; - a fit in which every estimated parameter is FIX (θ, Ω and σ, and Ω_IOV,
block_sigmacorrelations and[mixture]overrides where the model has them), so SIR has nothing to sample (E_SIR_NOTHING_TO_SAMPLE, on[parameters]).fit()withsir = truereports the same text as a warning; - a re-read of the fit’s model or data file that fails: the code and block
ferx checkgives the same file, so a re-read with a covariate column missing isE_MISSING_COVARIATEoncovariates. The message is the read’s own: anE_DATArefusal has noFailed to read data filelead (and one from the hash step names the file it could not open), and a model file read only for its reader settings adds why it was read and how not to need it.
The binders
The binders (bind_theta_levels, bind_covariate_stats, bind_from_fit, layout_from_fit) return an EngineError too, with the same two binding codes: E_THETA_LEVEL_BINDING on [parameters] for a level block, E_COVARIATE_STATS_BINDING on [covariate_model] for a statistic. A refusal only a binder from a fit can reach — a design level the fit estimated no θ for, or malformed fit bindings — has no ferx check counterpart, since ferx check --data binds the data to its own levels; it carries the code all the same. A fit with no bindings at all, on a model with a level block, is the level code.
The non-fit bundle
The rule is that a finding about the model or the data is carried; a finding about the fit’s configuration or the optimizer’s start is not — on these entry points there is no fit and no optimizer, so such a finding would be about something that is not happening.
Carried, in this order:
- Parse warnings — e.g.
W_ABSORPTION_TWIN_DECLINED, which changes what a prediction does. - Data-reader warnings —
W_CMT_DEFAULTED,W_ADDL_MISSING_II,W_IOV_OCC_MISSING, through the same suppression filterfit()andferx checkuse, so all three suppress exactly the same ones. - Model/data warnings —
W_STEADY_STATE_*,W_SDE_*,W_MODELED_*,W_ADDITIVE_INIT_SCALE,W_COMPARTMENT_FREE_DOSES,W_PER_CMT_UNMATCHED, … The last is the one whose membership was argued rather than inherited: a declared per-CMT entry that no observation matched is a statement about the model and the data the caller handed in, andpredict()dispatches through the same per-CMT map, so the entry is exactly as inert there as in a fit (#1405). Followed byW_NEGATIVE_LAGTIME: a negative lag at the typical values is the errorE_NEGATIVE_LAGTIMEonfit()andferx check, and this warning where the lag is served instead (#1189). - Experimental-feature notices — a feature is experimental whichever door you use it through.
- The ODE-solver diagnostics of the pass that just ran.
Ahead of the bundle, predict_diag(), predict_survival_diag(), both simulate_*_diag() forms and the adaptive driver (simulate_adaptive() / simulate_adaptive_from_spec()) also carry the steady-state non-convergence note of the pass that just ran: the uncoded message beginning “Steady-state (SS=1) equilibration…”, which fit() reports too. It fires when an SS=1 dose on a nonlinear [odes] model reaches the equilibration cycle cap short of steady state, so the returned trough is unreliable or biased low. Before #1652, predict_diag() and the adaptive driver ran the same capped equilibration and said nothing. Each of these calls reports only its own pass: a note left by an earlier call is cleared on entry. The thin wrappers (predict(), predict_survival(), simulate(), simulate_with_seed(), simulate_with_options(), simulate_with_uncertainty(); see the entry-point table) discard it along with everything else.
Not carried, and the reason is structural rather than editorial:
- The estimator/optimizer option warnings (
W_GN_NO_RANDOM_EFFECTS,W_VI_OMEGA_UNANCHORED, …). Their subject is a[fit_options]combination that is not running, and these entry points take no fit options at all, so reporting them would mean inventing defaults the caller never chose. - The packed-start rail warnings. Their subject is the vector the outer optimizer starts from; nothing is packed on a prediction or a simulation.
fit()’s operational notes — the finite-difference-fallback count, the thread-count hint, the covariance-step cost estimate.
Within what it carries the list is unfiltered on purpose. Two members are phrased for a fit (W_ADDITIVE_INIT_SCALE talks about optimizer basins; the modeled-duration checks call their values “initial estimates”), and they are still true of the numbers being served — a σadd that cannot absorb the data is as visible in a simulated DV column as in a fit. Dropping a code because it reads oddly outside a fit is what produced the “which entry point sees which finding” confusion in the first place.
One consequence worth knowing: W_ODE_SOLVER_DIAGNOSTICS from a non-fit() entry point describes that call, at the parameters you passed, and says so — "at the supplied parameters" and "Counters are from this predict() pass" rather than the post-fit sweep’s "at the final estimates". A discarded stiff escalation likewise says that this pass paid for both solves, not that a fit did. The ode_method named is the one stamped on the model by its own [fit_options], not a default.
Severity
| Severity | Meaning | Typical agent response |
|---|---|---|
Critical |
The result is untrustworthy as-is (no convergence, failed covariance, ill-conditioning). | Do not accept the model; change structure/inits and refit. |
Warning |
The result stands but a caveat applies (autocorrelation, shrinkage, data quality). | Inspect; often iterate on error model, IIV structure, or data. |
Info |
Informational note, no action implied. | Log; no action. |
Every Critical code except covariance_failed also becomes a reason in the fit’s status (FitResult::status()); the covariance failure is read there from covariance_status instead.
Warning codes
Each WarningCode token, what it flags, and a typical response. The groups below are for reading convenience only — the token is what a consumer branches on, and a code never moves between groups in a way that changes its category string.
Convergence and covariance
Two groups: whether the estimation itself finished somewhere usable, and whether the covariance step that followed produced usable standard errors.
Optimizer and estimate
Code (category) |
Severity | Flags | Typical agent response |
|---|---|---|---|
convergence |
Critical | Optimizer did not converge; or (W_NONFINITE_OBJECTIVE) the objective at the final estimates is NaN, infinite, or at or above the 1e14 divergence cutoff; or (W_NO_FEASIBLE_EVAL) not one outer trial was feasible — the EBE guard rejected them all, or every objective was non-finite — so nothing was minimised and the estimates are the ones the fit started from (#1617); or (W_ABOVE_START) the fit reported an objective materially above the one its starting estimates scored, restarts included, typically because the EBE guard rejected that first evaluation (#2461). or (W_NONFINITE_MARGINAL) the importance-sampling marginal −2 log L at the final estimates is NaN, infinite, or past the divergence cutoffs; or (W_MCEM_OBJECTIVE_ROSE) an IMP / IMPMAP final marginal sits far above the lowest value its iterations reached (#2652); or (W_MCEM_NOT_SETTLED) an IMP / IMPMAP run stopped at its iteration limit with its objective’s floor still falling, or well above the final marginal, or with too few finite iterations to read (#2686); or (W_MCEM_MSTEP_FROZEN) a θ or σ owned by the IMP / IMPMAP weighted M-step never left its starting value although a step along it still lowers −2 log L by more than 3.84; or (W_MCEM_MSTEP_FAILED) NLopt failed one of those solves (#2718); or (W_NON_STATIONARY_OPTIMUM) a FOCE-family estimate is not a stationary point: its Newton decrement exceeds 1 OFV unit (#2785). A W_MCEM_SETTLING_UNTESTED note is Warning, not Critical: the run was too short to test, and nothing was demoted. |
Reject; adjust inits / method / bounds and refit. For W_NONFINITE_OBJECTIVE, first find the record or parameter that poisons the objective — see A non-finite objective. For W_NO_FEASIBLE_EVAL, act on the cause named: inner_maxiter / max_unconverged_frac for the guard, the offending record for a non-finite objective (When no evaluation is feasible). For W_ABOVE_START, see When the fit ends above its start. For W_NONFINITE_MARGINAL and W_MCEM_OBJECTIVE_ROSE, see When the marginal shows a collapse. For W_MCEM_NOT_SETTLED and W_MCEM_SETTLING_UNTESTED, see When the objective has not settled. For W_MCEM_MSTEP_FROZEN and W_MCEM_MSTEP_FAILED, see When the M-step leaves a parameter behind. For W_NON_STATIONARY_OPTIMUM, see What converged guarantees. |
optimizer_health |
Warning | Trust-radius collapse / degeneracy, or a fit that stopped mid-descent and was restarted from the best point it reached. | Try a different optimizer or re-scale parameters. A restarted fit that ends converged needs no action; one that did not is usually short of maxiter. |
ebe_start_dependent |
Warning | (W_EBE_START_DEPENDENT) The empirical Bayes estimates at the final parameters depend on where the inner loop starts: re-solving them cold scores more than 0.05 OFV units worse than the EBEs the optimizer minimised against, or returns a non-finite objective (#833, #2646). Either the individual objective has more than one mode at these estimates, or the inner loop cannot reach it from a cold start within inner_maxiter — the message names both, since the two objectives do not distinguish them. Each subject keeps its lowest-scoring candidate, and the message names the subjects the cold solve missed on (details). Or, in the other direction, the cold re-solve scores materially lower than the objective the optimizer minimised — some subjects’ EBEs sat in a higher mode for the whole trajectory — and the restart that would have fixed it could not run or left a gap of its own; the fit is then converged: false (#1565, details). |
Worse direction: the estimates are usable; the EBE-derived diagnostics are the part to treat with care. Refit with a larger inner_maxiter (budget) and with inner_restarts raised (second mode) to tell the two apart, and compare IPRED / IWRES / shrinkage against that refit. Lower direction: the estimates are not the optimum — refit starting from them, with maxiter budget to spare. |
vi_bad_basin |
Critical | VI’s final ELBO tightness check found that a flat objective is an unusable variational bound, not convergence. | Reject the fit; use better starting values or initialize VI from a fitted point with method = [focei, vi]. |
Covariance step
Failures, the eigenvalue floor and conditioning
Code (category) |
Severity | Flags | Typical agent response |
|---|---|---|---|
covariance_failed |
Critical | Covariance step failed — no standard errors. Every message that starts Covariance step failed gets this code, whatever reason it goes on to give (a message carrying a W_ token is classified by its token first): a profiled fit’s “the profile solve did not converge at the estimates” is a covariance failure, not convergence, and says nothing about whether the fit converged (#2158). |
SEs unavailable — try covariance_fallback = sir or refit with different inits. |
covariance_regularized |
Warning | Covariance step succeeded but an eigenvalue floor was applied, or an off-diagonal stencil was non-finite, or (W_COV_NON_STATIONARY_ESTIMATE, #1781) S⁻¹ replaced an r / rsr whose R needed an eigenvalue floor at a sampler’s estimate. The message names which Hessian was floored (the exact analytic R-matrix, or the finite-difference stencil), and grades severity on magnitude — |min eig| / max eig, and the worst inflation the floor caused in a reported variance (measured on the covariance the fit returns, after the selected estimator and the reported-parameter delta transform) — never on how many eigenvalues were clipped (#520). The message prints min eig and max eig, and adds |min eig|/max eig only when the floored Hessian is indefinite (min eig < 0); a positive min eig means near-singular, not indefinite, and that ratio is not graded (#2132). Which of those two magnitudes carried the grade decides what the message then says about the standard errors. On the finite-difference route it also names every gate clause that declined the analytic R-matrix (e.g. analytic_cov_hessian = false, gradient = fd, a non-Gaussian endpoint, or a subject with more random effects than the R-matrix serves: 8 under Laplace’s exact anchor, 24 otherwise), promising a route change only where the named one-line action clears all of them, and names the integration tolerance when the model — or a closed-form absorption model’s ODE twin — integrates looser than ode_reltol = 1e-6 / ode_abstol = 1e-8 — since #520 a step that runs the stencil is tightened whole to that plateau (also for a segment a matrix-exponential solve declines to the integrator), so this is reached only when that tighter run could not be set up, which W_COV_ODE_TOLERANCE_NOT_TIGHTENED reports. |
minor needs no action. At moderate/severe, read which magnitude the message blames: an inflated reported variance means those SEs came substantially (severe: mostly) from the floor rather than from the data, while an indefinite Hessian with no inflation means the floor rewrote curvature the reported SEs do not load on. Either way, act on the named clause if the message says it is the only one (setting analytic_cov_hessian = true or dropping gradient = fd moves the fit onto the analytic route), tighten ode_reltol/ode_abstol if the message names them, and use SIR intervals. In a model search, the eigenvalue-floor message fails the strictness gate whenever max_condition_number or max_correlation is set, at every severity (#1512). |
condition_number |
Critical | Ill-conditioned covariance / high condition number. The figure is only meaningful next to the estimator that produced it — read covariance_method from the details payload, or from the fit (Which covariance estimator produced these numbers). |
Over-parameterized — drop a random effect or covariate. |
Covariance-step notes
Code (category) |
Severity | Flags | Typical agent response |
|---|---|---|---|
covariance_step |
Info / Warning | Covariance-step note (e.g. evaluation cost). W_COV_ODE_TOLERANCE_NOT_TIGHTENED (Warning): an integrated model’s covariance step, which finite-differences its R or S matrix, could not be run at ode_reltol = 1e-6 / ode_abstol = 1e-8 and ran at the fit’s looser tolerance, so the SEs may be inflated; pin those tolerances to compute them at the plateau (#520). A step that then fails reports no SEs and carries no such warning: its covariance_failed message says instead that it ran at the fit’s own tolerance, and why. W_COV_QUADRATURE_OBJECTIVE (Info) / W_COV_QUADRATURE_DECLINED (Warning): which objective the step differentiated after saem / imp / impmap on a non-Gaussian model (details). W_COV_NN_PENALTY (Info under r / rsr, Warning under s): whether a regularized covariate-NN fit’s SEs include the penalty (details). W_COV_NON_STATIONARY_ESTIMATE (Warning, this form only): R was positive definite and its SEs were returned at a saem / imp / impmap / vi estimate whose gradient says it is not a stationary point of R’s objective (details); the token’s floored-R forms are covariance_regularized and covariance_failed. W_COV_RSR_ONE_SUBJECT_LEVELS (Warning): an rsr step reported SEs for θ levels that a single subject reads, which it cannot inform; the message counts them per block (details). |
None; for …_DECLINED and W_COV_NON_STATIONARY_ESTIMATE, polish with a FOCEI stage before relying on the SEs. |
Residual and random-effect diagnostics
Code (category) |
Severity | Flags | Typical agent response |
|---|---|---|---|
dw_autocorrelation |
Warning | IWRES autocorrelation: the pooled Durbin–Watson statistic is out of range, or, under a correlation … by line whose blocks run in time, the statistic over the pairs that join two blocks is below 1.5 while the pooled one is in range (Occasions in time). |
Revisit the residual-error / structural model. The positive message’s advice depends on the model: structural remedies for a model with compartments, a correlation ar1(RHO) by … line for a compartment-free one (MBMA). |
eta_normality |
Warning | ETA departs from normality. | Consider a mixture or transform. |
Censoring, resampling, and experimental features
Code (category) |
Severity | Flags | Typical agent response |
|---|---|---|---|
experimental |
Warning | An experimental feature (SDE, neural-network) was used. | Treat results with caution; validate. |
bloq_method |
Warning | BLOQ / M3 censoring caveat. | Confirm the censoring semantics match intent. |
sir |
Warning | SIR failed or was requested without a covariance; its proposal needed repair; or its effective sample size is below 100, naming the heaviest draw and any variance the data do not bound away from zero. | Ensure a covariance exists before requesting SIR. Below an ESS of 100, increase sir_samples; for a named variance, do not read its SIR lower limit, and consider sir_scale = natural (SIR). |
importance_sampling |
Warning | ESS = 0 / proposal collapse. | Increase samples or improve the proposal. |
Shrinkage and parameter identifiability
Code (category) |
Severity | Flags | Typical agent response |
|---|---|---|---|
eps_shrinkage |
Warning | Residual (EPS) shrinkage high / negative. | Sparse data for the error model — simplify it. |
eta_shrinkage |
Warning | One or more ETA shrinkages exceed ~30%. | Data poorly inform that IIV — consider removing it on the affected parameter(s). |
boundary_estimate |
Warning | One or more THETA estimates are pinned to an optimizer bound. | Non-identifiability or a too-tight bound — inspect; relax the bound or simplify. |
stalled_at_init |
Warning | The fit never left its initial estimates — no free THETA, OMEGA or SIGMA coordinate moved, so the reported objective is the objective of the initial values. Unless the start was already an optimum, that says nothing about the model; the start could not be verified as one (another estimator, a restart with no budget left, or an inconclusive one), and the message says so. Usually arrives alongside converged: true: a fit that never moved has a perfectly flat objective trace to plateau on, which is why this is not convergence (#997). Read from the optimizer’s own scaled-space escape test when the run recorded one, otherwise from a comparison against theta_init / omega_init / sigma_init. |
Do not read the OFV as a statement about the model. Try different initial estimates, or a gradient-based optimizer if the fit used a derivative-free one, and check final_gradient at the reported point. A start the NLopt outer loop verifies as an optimum (a restart from a perturbation of it converges back, as a warm start from a previous fit’s estimates does) is not flagged at all, and a stall that restart improves on stays flagged — the reported estimates are still the ones that did not move — with a further warning naming the lower objective the restart reached (#2506, details). |
init_outside_bounds |
Warning | An initial estimate packs outside one of ferx’s internal rails (the hidden 1e9 THETA cap, the OMEGA ±6 / off-diagonal ±10 guards, the SIGMA [-8, 5] guard) and was clamped there before the first objective evaluation. A start, not a result — distinct from boundary_estimate for that reason, and it does not count as an estimate near a boundary. |
Move the initial estimate inside the rail. A THETA outside its own declared range is refused outright instead (E_THETA_INIT_OUTSIDE_BOUNDS), except on an evaluation-only run (maxiter = 0): there it carries this category too, as W_THETA_INIT_OUTSIDE_BOUNDS, and the reported OFV is that of the bound. Widen the declared range to score the declared value. |
parameter_at_runaway_guard |
Critical / Warning | A free coordinate is pinned to a hidden optimizer guard (implicit THETA cap, OMEGA / SIGMA rail), with a verdict the side does not decide. |
collapse (Warning): remove or simplify it. Its standard error is not reported: it is listed in FitResult::held_at_bound, and when the covariance step’s R was clean the step holds it and the other SEs are conditional on it (held parameters); the message says which. runaway (Critical): converged: false — reject; revisit model, data, inits; for SIGMA, rescale DV. A runaway is never held. |
inflated_rse |
Warning | One or more THETA estimates have RSE > ~50%. | Imprecisely estimated — often over-parameterization; consider simplifying. |
high_correlation |
Warning | One or more THETA (fixed-effect) pairs have |correlation| ≥ 0.95. | Over-parameterization / non-identifiability — fix or remove one of each pair. |
Dataset and model structure
Code (category) |
Severity | Flags | Typical agent response |
|---|---|---|---|
data_quality |
Warning | Dataset issue (missing DV, ADDL/II, non-positive DV, …). | Fix the dataset before trusting the fit. |
omega_structure |
Warning | Mixed lognormal / additive block in omega. | Make the block’s parameterization consistent. |
degenerate_clearance_or_volume |
Warning | W_DEGENERATE_CL_V: the final estimates put a non-positive or non-finite CL or V on at least one dose, observation, EVID=2 or EVID=3/4 record of a 1-/2-/3-cpt IV / oral closed-form model, each record read under its own covariates and occasion κ (#2104); an EVID=4 row is one record, a separate EVID=3 row beside a dose is two. A non-positive or infinite value is served a concentration of 0 by both closed-form engines, which also drop any drug in the body over an interval it governs, so the fit scored a confident, finite prediction; a NaN (a covariate value the expression cannot use) gives an observation NaN once a dose has arrived, repelling that subject’s likelihood, and 0 before any dose. The message states the rule for each kind that occurred, with its record count. NONMEM would refuse both — PREDPP rejects a non-positive PK parameter as an error. Names the subjects, the record count and the first offending TIME; details carries n_zero_records, n_nan_records and each subject’s times / nan_times. |
Usually a linear covariate term such as CL = TVCL * (1 + THETA * (AGE - 40)) going negative on an extreme record, or a missing / out-of-domain covariate. Use a form that keeps CL and V positive (exponential or power), bound the covariate effect, or fix the data. |
Run configuration and informational notes
Code (category) |
Severity | Flags | Typical agent response |
|---|---|---|---|
gradient_fallback |
Info | A gradient / sampler fallback was taken. | None; note the slower path. |
mu_referencing |
Warning / Info | Missing or partial mu-referencing. | Prefer CL = TVCL * exp(ETA_CL) forms for SAEM/Bayes. |
optimizer_config |
Warning / Info | global_search config note or failure. |
Check the global-search setup if disabled unexpectedly. |
multi_start |
Info | Multi-start notes: how the starts compare (on every multi-start fit), and which starts failed. | Check whether the converged starts agree; see What the starts did. |
cancelled |
Info | Run cancelled by the user. | None. |
threads |
Info | Thread-count efficiency note. | Optionally tune threads. |
simulation |
Warning | A simulated subject was handled specially — a degenerate hazard draw (censored, no event) or an over-large recurrent-event stream (skipped/truncated). Surfaced by simulate_with_options_diag and on --simulate runs (#762/#763). Also W_IOV_NO_OCCASIONS: a kappa model simulated subjects that carry no occasion label at κ = 0, with no inter-occasion variability, from simulate_with_options_diag and simulate_with_uncertainty_diag (#1955), or simulated their NPDE/NPD reference distribution that way, from compute_npde_npd_diag (#1980). Also W_FREM_DRAWN_ETA: a FREM model simulated subjects at an η drawn from Ω, covariate η included, so their PK does not follow their own covariate values (#2245). Also W_ADAPTIVE_DECISION_BEFORE_MOVED_RESET: an adaptive decision point runs before a reset the data reader moved, although it was written after it, so the reset removes that decision’s dose (#2559). Also W_ADAPTIVE_DOSE_ORACLE: under dose_knowledge = oracle, some subjects were dosed from their drawn individual values, a perfect-information arm (#944). Also W_ADAPTIVE_STEP_ABSORBED: with round_to, the smallest increase N% rounds back to the same dose at a dose some subjects can be at, so that rule cannot raise it (#2810). |
Inspect the named subject’s hazard parameters / covariate values; the estimated model is unaffected. For W_IOV_NO_OCCASIONS, label the occasions in the data (iov_column) or pass the model’s iov_occasion rule; see IOV: Simulation. For W_FREM_DRAWN_ETA, supply the FREM fit’s EBEs or set match_method; see FREM: Limitations. For W_ADAPTIVE_DECISION_BEFORE_MOVED_RESET, add the shift the warning names to the decision times after that reset; see Adaptive dosing: Decision times after a moved reset. W_ADAPTIVE_DOSE_ORACLE is informational: the flagged subjects are in the metrics’ dose_oracle; see Adaptive dosing: Which subjects’ values are known. For W_ADAPTIVE_STEP_ABSORBED, use a smaller round_to or a larger increase step, or, where the upper bound allows, raise the start dose and the low of dose_bounds to the lowest dose the warning says the step can raise; see Adaptive dosing: Rounding doses to a grid. |
Absorption diagnostics
Code (category) |
Severity | Flags | Typical agent response |
|---|---|---|---|
flip_flop |
Warning | A transit / inverse-Gaussian absorption closed form entered the flip-flop regime (disposition rate ≥ the tilting abscissa). One cause, three phases: auto-rerouted to the ODE twin (informational); or, on a twin-less model, a silently degenerate likelihood contribution at a subject’s fitted EBE (#785), or W_SIMULATED_FLIP_FLOP — a per-run count of the simulated individuals dosed before one of their observations whose sampled η crossed, so none of their rows carries anything from the doses the subject was given (they are undosed, not drug-free — an [initial_conditions] baseline survives the clamp); not necessarily ipred == 0.0, because a baseline / Form-C readout / log transform / FREM override can run after the clamp (#1823). |
Rewrite as an explicit ODE transit()/igd() model (which reroutes per subject and per simulated individual), or check the named subject’s MTT/CL (transit) or MAT/CV²/CL (IG) estimates. |
uncertainty_draws_skipped |
Warning | simulate_with_uncertainty_diag() skipped some parameter draws because they fell in the flip-flop regime of a twin-less transit / inverse-Gaussian closed form (#1485). One warning per run, with the count and the 1-based draw indices. The surviving draws are a truncated sample, so intervals built from them are biased. |
Rewrite as an explicit ODE transit()/igd() model, which simulates every draw; otherwise treat the interval as one-sided. |
absorption_twin_declined |
Warning | An analytic transit / inverse-Gaussian model’s ODE twin could not be built, so the model keeps no ODE fallback (#1008). The fit itself is an ordinary closed-form fit; what is lost is the reroute, so a subject needing it (time-varying covariates, a TIME-dependent parameter, IOV, SS / infusion doses, the flip-flop regime) is rejected with an explicit error. |
Read the quoted reason — usually an individual parameter named after a twin state (CENTRAL, PERIPH); rename it to restore the twin. |
Solver, numerics, and unclassified
Code (category) |
Severity | Flags | Typical agent response |
|---|---|---|---|
flat_parameter |
Warning | A non-fixed THETA has an ≈ 0 outer gradient at the initial estimate — it never reaches the objective (unmapped, or dropped from the structural / scaling model). The pre-flight guard froze it at its initial value so the remaining parameters could estimate, instead of the whole fit dying on an eval-1 optimizer Failure (#826). |
Map the named parameter into the model, or remove it. Its reported estimate is just its initial value (SE = N/A). |
ode_solver |
Warning / Info | The ODE solver’s own health at the final estimates (#1080). Warning when steps clamped at the minimum step size (a stability-limited segment whose un-integrated tail is freeze-padded), when a segment stopped before its requested end, when ode_stiff_abort_after cut segments short, or when ode_method = auto discarded an escalation and re-solved it explicitly — including when only its analytic derivatives overflowed, its values staying finite — and when that re-solve failed too. Also Warning when a prediction walk was abandoned before integrating because the subject’s timeline could not be ordered — a NaN or infinite dose time, lagtime, route lag, or infusion duration (#1234). That case leaves every step counter at zero, so it is reported by its own counter (abandoned_non_finite_timeline) rather than inferred from the others. Also Warning when a state became non-finite mid-segment, meaning the [odes] right-hand side diverged (diverged_segments, #1539). The segment’s remaining output times are then NaN in every state rather than freeze-padded, so these two are the cases whose predictions are NaN rather than merely inaccurate. Info when auto escalated and everything worked (a separate W_ODE_SOLVER_ESCALATION_NOTE token, so the severity survives re-classification) — routine on a stiff model, but a decision you never asked for and cannot otherwise see. Both severities report how many segments changed stepper part-way through (ode_auto_switch, default on): steps before a switch were taken by a different method than those after. W_FD_JACOBIAN_NOT_TIGHTENED (Warning): some subjects’ finite-difference Jacobian at the final estimates could not be integrated cleanly and was taken at the fit’s own ODE settings, so the OFV may be off (#2701). |
A rejected escalation means the probe was right about the stiffness and wrong about the method: name ode_method = rodas5p (or rosenbrock23). Non-zero auto_stiff_rejected_jets is the exception: the method worked, the sensitivities overflowed — check units and scaling, not ode_method. Non-zero auto_fallback_failed: neither attempt gave a usable trajectory; do not trust the fit. Clamps with no rejection mean the explicit stepper is stability-limited — try a stiff method, or loosen ode_reltol / ode_abstol. Non-zero diverged_segments is not a solver problem either: no ode_method integrates a state that has become non-finite, so the message drops its solver advice when every damaged segment diverged. Check the [odes] right-hand side and the parameter values that drive it. Non-zero abandoned_non_finite_timeline is not a solver setting at all: some subject’s timeline is unorderable, so check the dose records and any exponential covariate model on ALAG / F / D / R for a value that overflows at typical covariates. For W_FD_JACOBIAN_NOT_TIGHTENED, raise ode_max_steps or ode_stiff_abort_after, or name a stiff ode_method. |
general |
Warning | Unrecognised message (fallback bucket). | Read the message text. |
A non-finite objective
converged is the field most consumers branch on, so it is never true at an objective that is not a usable number. Whenever the reported OFV is NaN, infinite, or at or above the 1e14 cutoff, the fit comes back with converged: false and a W_NONFINITE_OBJECTIVE warning saying which it was:
NaNorinfinite;- at the divergence sentinel — finite and, when read from the subjects, at least one subject’s objective was clamped (one clamped subject alone contributes
2e20) or refused outright (IOV combined with FREM is refused at1e18). When read from the total, it means only that the objective is at or above1e20; see the paragraph after this list; - too large to be a fit — finite, past the cutoff, and, when read from the subjects, no subject was clamped: some subject’s objective is that large on its own terms (read from the total, it means below
1e20). A proportional error on a prediction of0does this: the zero residual variance is replaced by1e-12, and each such observation scores aboutDV² × 1e12. The cutoff applies to the summed objective, so the warning is raised once the sum ofDV²over those observations, across the population, exceeds 100. One largeDVcan do it alone, and many small ones can add up to it. A singleDV = 4.4gives1.9e13and does not raise it on its own, and a singleDV = 12000gives1.44e20, past the clamp value without being clamped.
The estimators see only the population total, so the label they write is drawn at 1e20: the sentinel at or above it, too large below it. fit() sees the subjects and rereads the label from them (#2265) when they are the objective: the contributions are its terms (see Contributions from another objective), and their sum, with the parameter-prior penalty, is past the cutoff and equals the objective up to rounding (a relative 1e-9), counting a non-finite contribution at the 2e20 it was clamped to. Otherwise, for example when the objective was evaluated at another point than the subjects are scored at, the label stays the total’s reading, which is the likelier reading rather than a proof. The reason_read_from detail says which reading the label is, "subjects" or "total". Which subjects describes the subjects themselves.
is_finite() is deliberately not the test. A repelled fit — one the optimizer walked into a region where an individual contribution blows up — is clamped to a finite ~1e20 sentinel, so it would pass a finiteness check while being no more a solution than a NaN is. The threshold is 1e14, far above any legitimate population OFV (real −2 log L values reach at most ~10⁶–10⁷ even for very large cohorts) and far below the sentinel. The cutoff is one-sided: a large negative objective is legitimate on log-transformed data.
What it means for the result
The parameter estimates, per-subject diagnostics and remaining warnings are still returned — they are what you need in order to find the offending record — but nothing derived from the objective is meaningful: the OFV, AIC, BIC, the standard errors, and any likelihood-ratio comparison against another model. Treat the run as failed.
A single bad subject is enough. The objective is a sum over subjects, so one NaN contribution destroys it for the whole population, including subjects that fitted perfectly well.
What to look for
The usual causes, in rough order of how often they turn up:
- a non-finite dose time,
lagtime/ALAG{n}, bioavailabilityF{n}, infusion durationD{n}or rateR{n}in the data or produced by the parameter model; - a covariate model that overflows at an observed covariate value —
exp()is not clamped in the DSL, soALAG1 = TVLAG * exp(WT)on an unscaled weight reaches+inf; - a residual variance driven to zero, making the individual likelihood infinite;
- a prior (
prior(...)) whose penalty overflows at the final estimates — the reported OFV isofv_data + ofv_prior, so the likelihood half can be perfectly finite while the published total is not.ofv_dataandofv_priorare reported separately, which tells the two apart immediately.
If the model also carries a W_ODE_SOLVER_DIAGNOSTICS warning with a non-zero abandoned_non_finite_timeline, that is the first place to look: it means a subject’s timeline could not be ordered and its predictions are NaN by construction.
Which subjects
When the subjects’ own contributions at the final estimates show where the objective went wrong, the warning ends with one more sentence naming them (#2038). A subject is named when its objective contribution is itself unusable (NaN, infinite, or past the cutoff). For each one it gives the contribution and two clauses, each with a TIME as written in the data:
1 of 10 subjects have an objective contribution that is itself unusable:
3 (contribution 2e20, an unusable likelihood term on 1 of 12 observations, the
first at TIME 0 (DV 200, IPRED 0); every IPRED and PRED finite).
The first clause names the observations whose own likelihood term is unusable (#2266), and the DV and IPRED of the first. That term is the record’s −2 log L in the FOCEI conditional data term at the subject’s EBE, read off the scorer’s own computation, with the raw IPRED and the fitted residual variance. It includes the fitted residual correlations, an SDE’s process noise, an iiv_on_ruv scale and an M3 censored term. A mixture subject is scored under its fitted class. The term is unusable when it fails the same test as the objective (NaN, infinite, or at least 1e14), or when the scorer cannot use its variance at all. Start with this record. Above, the prediction at TIME 0 is a finite 0, which a proportional error scores at the guarded variance 1e-12, DV² × 1e12. No prediction is non-finite, so the prediction clause has no record to name. A runaway iiv_on_ruv random effect is caught the same way: its variance overflows to infinity, so the record is named even though IWRES reads 0. Under FOCE, or residuals correlated across records, the objective does not split by record, and the term is what the record contributes at the EBE on its own. When the subject cannot be matched to its data, the clause reads likelihood terms not checked.
The second clause names the observations whose IPRED or PRED is not finite:
3 (contribution 2e20, an unusable likelihood term on 8 of 11 observations, the
first at TIME 4 (DV 11.0602, IPRED NaN); a non-finite IPRED or PRED on 8 of 11
observations, the first at TIME 4).
Here the model’s CL went non-finite at TIME 4, and every later prediction of the subject inherited it. On that record the parameter model (a power of a negative covariate, a log of zero) or the structural model produced a value the likelihood could not score.
The two clauses can name different records. A runaway random effect can leave an early record with a finite prediction of 0 that the residual model already cannot score, and the first non-finite prediction then comes after it. The two engines can also disagree on the predictions for the same subject: on such a subject the closed form may report a non-finite prediction at one record and finite ones elsewhere, where the ODE solver reports the opposite. The likelihood-term clause names the same record on both, so read that one first.
When neither clause names a record (every observation's likelihood term usable on its own; every IPRED and PRED finite), the cause is not in a single Gaussian record. Many records whose terms are each large but below the cutoff can add up past it. A non-Gaussian term can do it as well (a time-to-event, binary or Markov likelihood), as can a covariance matrix that is not positive definite, or a subject the likelihood refuses outright, such as IOV combined with FREM. The term clause below says which.
Which term failed
The sentence then names each separately scored part of the subject’s likelihood whose own value is unusable (#2267). A subject with all predictions finite reads every IPRED and PRED finite, or no Gaussian observation when it has none (a time-to-event-only subject, for example), and the named term is where to look:
1 of 30 subjects have an objective contribution that is itself unusable:
3 (contribution 2e20, no Gaussian observation, failed term: time-to-event on
CMT 2 = 1e20).
The parts are recorded by the marginal that scored the contribution, on the branch it took, so a healthy subject’s parts sum to its contribution under FOCE and FOCEI alike. A failed factorization stops the marginal: the part that failed is listed as NaN under a name saying why, and the parts after it are absent.
| Term | Branch | What it is | Typical cause |
|---|---|---|---|
Gaussian residual term |
FOCEI | ½(rᵀR⁻¹r + ln\|R\|) at the subject’s EBE |
a proportional error on a prediction of 0, about DV² × 1e12 per observation (the zero variance is replaced by 1e-12); a NaN prediction |
Gaussian residual variance (non-finite or non-positive) |
FOCEI | in place of the residual term when a row’s variance cannot be used | a residual model returning NaN or ≤ 0 |
Gaussian residual covariance R (not positive definite) |
FOCEI, correlated R |
in place of the residual term when R does not factor |
a residual correlation outside its admissible range |
linearized residual term |
FOCE | ½ rᵀR̃⁻¹r, r = y − f₀, over the quantified rows |
as for the Gaussian residual term, at PRED |
linearized covariance log-determinant |
FOCE | ½ ln\|R̃\|, R̃ = HΩHᵀ + R |
a variance or ∂f/∂η past the cutoff |
linearized covariance R̃ (not positive definite) |
FOCE | in place of the two above when R̃ does not factor |
a non-finite ∂f/∂η or variance |
censored (M3) term |
both | the censored rows’ −log Φ tail, under bloq_method = m3 |
an LLOQ far from the prediction |
random-effect prior |
FOCEI | ½(η̂ᵀΩ⁻¹η̂ + ln\|Ω\|) (FOCE carries it inside R̃) |
a runaway EBE |
curvature log-determinant |
FOCEI | ½ ln\|H̃\|; named curvature (H̃ not positive definite) when it does not factor |
a non-finite ∂f/∂η, or censored rows the model cannot fit |
time-to-event on CMT n, categorical, CTMM |
both | each non-Gaussian data term | an overflowing or non-positive hazard (the 1e20 sentinel) |
non-Gaussian curvature (η-Hessian … not finite) |
both | in place of the curvature, when those terms’ η-Hessian is not finite | a hazard that overflows next to the EBE |
curvature (H̃ not positive definite once the non-Gaussian Hessian is added) |
both | in place of the curvature, when the Gaussian side alone factors | a non-Gaussian term strongly non-convex at the EBE |
IOV + FREM refusal |
IOV | the value the IOV likelihood returns for a subject with FREM covariate rows, which it does not support | the combination itself |
IOV random effects (κ̂ do not match the occasion groups) |
IOV | in place of every part, when the marginal refuses the subject’s κ̂ | an EBE vector of the wrong shape |
A subject with time-to-event, categorical or CTMM records is scored by the joint conditional form under FOCE as well, so its parts are the FOCEI names, and its curvature carries those terms’ η-Hessian (exact where the endpoint has a dual program, finite-differenced otherwise). An IOV subject’s marginal is over the stacked [η, κ] system, and its parts are that marginal’s: the same names, with the random-effect prior over η̂ and every occasion’s κ̂, and the curvature and FOCE’s R̃ over both.
A term is listed when its value is NaN, infinite, or past the cutoff once put on the contribution’s 2· scale. The message shows the raw negative log-likelihood, so a term printed as 6e13 is listed. When every scored term is usable the sentence says every separately scored term usable. The failure is then in how the parts combine, not in any one of them: only their sum is past the cutoff.
A subject with a non-finite prediction and a valid contribution is not named. IPRED and PRED are NaN by convention on a subject with no Gaussian observation, and that subject contributes nothing wrong. The message names at most ten subjects. The unusable_subjects array in the structured warning’s details lists all of them; see Where details is written for the outputs that carry it.
When no subject is named
When every subject’s contribution is valid, the warning says why no subject can be named (#2267), with the first of these that applies:
- The parameter-prior penalty is unusable.
fit()adds it to the data objective, and no subject carries it:...and the parameter-prior penalty, a population-level term no subject carries, is not (inf).An unusable penalty next to named subjects is added after the list instead. - The objective is not the sum of the contributions — see below.
- Only the sum is past the cutoff, as with ten subjects of
1.6e13each. The warning then names the largest contributions, largest first (#2265):...but their sum (160000000000000.0) is past the cutoff. The objective fails only as a sum; largest first, they are 1 (16000000000000.0), 2 (16000000000000.0), .... With more than ten subjects it names the ten largest and their share:the 10 largest of 250, together 37% of the sum of the contributions, are .... Thelargest_subjectsdetail lists the same subjects as{id, ofv_contribution}objects. - The sum is usable, so the objective was evaluated at another point than the estimates and EBEs the subjects are scored at — a trial point an optimizer stopped on, for example.
Contributions from another objective
The contributions are always the post-hoc FOCE/FOCEI score at the EBEs, and ferx classifies the objective by what was published rather than by the method name. FOCE, FOCEI, both Gauss–Newton methods, SAEM, IMP, IMPMAP and VI’s vi_final_ofv = laplace all publish the sum of these same scores. The ones that do not are Laplace and adaptive quadrature (n_agq > 1, including an agq_eval_only readout), BAYES (whose ofv is a joint NLL at the posterior mean), and a mixture’s class-marginal (#2267). After a list of named subjects the warning then adds:
These are post-hoc FOCEI contributions at the EBEs, not terms of the LAPLACE
objective, which ferx does not split by subject.
When no subject is named, such an objective gives:
No subject can be named: every subject's post-hoc FOCEI contribution at these
estimates is usable, but the LAPLACE objective is not their sum and ferx does not
split it by subject, so these scores cannot locate its failure; their sum (24.68)
is usable.
The sum is reported for what it is: the scores can sum past the cutoff themselves (...is past the cutoff as well), so neither case says the failure is in a part of the objective the scores do not share.
The structured warning’s details record this as contribution_score ("FOCE" or "FOCEI", the marginal the contributions score), contributions_are_objective_terms (false for such an objective) and ofv_prior; unusable_subjects is then present and may be empty. Each subject’s failed_terms lists the terms named in the message as {term, nll} objects, nll raw and a string when it is not finite.
The one exception
method = vi with the default vi_final_ofv = none reports ofv: NaN on purpose — the ELBO is a lower bound on the log likelihood, not a −2 log L, and reporting no number is safer than reporting one that looks like an OFV and is not. That is a declaration that no objective was published rather than a failed one, so it does not demote converged, and VI warns separately saying so. Set vi_final_ofv = laplace to get a real objective; it is then gated like every other method’s.
The exemption follows the objective, not the position in a method chain. A trailing imp_eval_only readout (method = [vi, imp], the recommended way to finish a VI fit) reports its importance-sampled −2 log L under importance_sampling and leaves VI’s NaN in ofv, so that fit stays exempt. A trailing agq_eval_only readout instead replaces ofv with its quadrature marginal, so that objective is gated — it is a real number that can fail.
Details payloads
Numeric diagnostics may carry a details object with the value behind the message, so a consumer reads the number directly instead of parsing prose. The numbers are sourced from the fit’s typed fields, not from the message text. Treat details as optional: check for its presence rather than assuming it.
| Code | details keys |
|---|---|
dw_autocorrelation |
durbin_watson, iwres_lag1_autocorr (both the pooled values, also on the cross-block warning, whose own statistic and pair count are in the message only) |
eps_shrinkage |
eps_shrinkage (fraction), eps_shrinkage_pct |
eta_shrinkage |
threshold_pct, high_shrinkage_etas (array of {eta, shrinkage_pct}) |
boundary_estimate |
parameters (array of {parameter, estimate, bound, side}) |
stalled_at_init |
verdict_source (optimizer_escape_test / natural_scale), n_free_parameters, theta (array of {parameter, estimate, init}) |
parameter_at_runaway_guard |
guard_space ("packed"), parameters (array of {parameter, estimate, packed_estimate, packed_guard, side, verdict, held}; held is true only when the covariance step held that coordinate, mirroring cov_fixed) |
inflated_rse |
threshold_pct, parameters (array of {parameter, estimate, se, rse_pct}) |
high_correlation |
threshold, pairs (array of {parameter_a, parameter_b, correlation}) |
flip_flop |
phase ("ebe"), model, subjects (array of affected subject IDs) |
ode_solver |
phase ("postfit_predictions"), ode_method, attempted_steps, accepted_steps, rejected_steps, min_step_clamped_steps, stiff_min_step_clamped_steps, discarded_clamped_steps, kept_clamped_steps, auto_stiff_segments, auto_switched_segments, auto_stiff_rejected, auto_stiff_rejected_jets, auto_fallback_failed, unfinished_segments, discarded_unfinished_segments, kept_unfinished_segments, stiff_aborted_segments, abandoned_non_finite_timeline. These are not all disjoint: kept_unfinished_segments is a roll-up that already includes stiff_aborted_segments, and auto_fallback_failed ⊆ auto_stiff_rejected ⊆ auto_stiff_segments. auto_stiff_rejected_jets is the one key not from the prediction pass — it comes from the post-fit sensitivity sweep, so it is disjoint from the rest, not a subset. abandoned_non_finite_timeline is disjoint too, and for the opposite reason: every other key describes a segment that started, and an abandoned walk never called the solver, so all of them are zero for it. It counts walks, not subjects — one subject whose predictions and whose [odes] state readout are both requested contributes more than one (measured: 3 per subject on a plain FOCEI post-fit sweep). The message text subtracts the overlaps before reporting; a consumer reading the payload should not add these keys together. |
convergence (W_NONFINITE_OBJECTIVE only) |
ofv (the offending value — a JSON number when finite, otherwise the string "NaN" / "inf" / "-inf", since JSON has no non-finite numbers), reason ("NaN", "infinite", "at the divergence sentinel" or "too large to be a fit"), reason_read_from ("subjects" when reason was reread from the subjects, else "total"; A non-finite objective), divergence_cutoff (1e14, the value at and above which a finite objective is unusable), method (the stage that produced the objective); and, when a subject’s own contribution is unusable, unusable_subjects — one object per such subject with id, ofv_contribution (number, or string when non-finite), nonfinite_predictions (observations with a non-finite IPRED or PRED), n_obs and first_time (the written TIME of the first; null when there is none, the subject is unmatched, or that TIME is not finite), and unusable_terms / first_unusable_term_time, the same for likelihood terms, and failed_terms; with it, contribution_score, contributions_are_objective_terms and ofv_prior (Which subjects); and, when the message names the largest contributions (When no subject is named), largest_subjects — at most ten, as {id, ofv_contribution}, largest first |
covariance_failed, covariance_regularized |
covariance_method, condition_number, min_eigenvalue, n_negative_eigenvalues (each present only when computed — a hard failure with no matrix omits the eigenvalue keys, and covariance_method with them) |
condition_number |
condition_number, covariance_method ("r" / "s" / "rsr" — omitted, never null, when no covariance matrix was produced) |
{
"severity": "Warning",
"category": "dw_autocorrelation",
"message": "Positive IWRES autocorrelation detected (Durbin-Watson = 1.20).",
"source_method": null,
"details": { "durbin_watson": 1.20, "iwres_lag1_autocorr": 0.40 }
}IMP and IMPMAP payloads
The checks on an IMP / IMPMAP fit carry these keys under the convergence code.
| Code | details keys |
|---|---|
convergence (W_NONFINITE_MARGINAL only) |
marginal, reason |
convergence (W_MCEM_OBJECTIVE_ROSE only) |
marginal, lowest_iteration_objective, rise, tolerance |
convergence (W_MCEM_NOT_SETTLED only) |
reason and window. For falling: previous_floor, floor, previous_mc_se, mc_se. For above_marginal: floor, mc_se, marginal, marginal_mc_se. For unusable_trace: usable, needed |
convergence (W_MCEM_SETTLING_UNTESTED only) |
iterations, needed |
When details is absent
A code omits the details key entirely (Rust field None) when it has no associated stored statistic, or when any contributing statistic is non-finite (NaN/±Inf — e.g. the condition number of a near-singular parameter space).
W_NONFINITE_OBJECTIVE is the exception to that second rule rather than an instance of it: the offending value is the payload, so a non-finite ofv is carried as the string "NaN" / "inf" / "-inf" (JSON has no non-finite numbers) instead of dropping the key. Only convergence warnings raised by this check carry details; a plain “did not converge” carries none.
Where details is written
A payload is part of the fit’s output, not only of the Rust value (#2268):
- Rust API —
FitResult::warnings_structured. - JSON output — each entry of
warnings_structured, as above. - YAML output — a
warning_details:list afterwarnings:, one item per warning that has a payload, with itscode,severity,source_method(when set),messageanddetails. The strings and the payload are written as JSON, which YAML reads as flow syntax.warnings:itself stays a list of message strings, and the block is absent when no warning has a payload. .fitrx—fit.jsonstores the entries that have a payload underwarning_details, and a reload restores them unchanged. Every other entry is rebuilt fromwarningson load, the way a fresh fit builds it.
The R package reads warnings_structured without the details column until its matching change lands.
How codes are assigned
Most codes are assigned centrally by classify_warning(), which maps each engine message to its WarningCode and severity, after which details is attached from the fit’s typed numeric fields for the codes above. classify_warning() is the single, type-checked source of the taxonomy: codes are WarningCode enum variants rather than free strings, so the vocabulary is centrally defined and cannot drift. The enum is #[non_exhaustive] — new codes may be added over time, so consumers should treat an unrecognised token as a generic warning rather than assuming a fixed, closed set.
Some warnings are instead emitted typed at their source: the site constructs a WarningEntry (code, severity, message, and a details payload) directly — boundary_estimate is the first — and that entry takes precedence over re-classifying the message string. Migrating the remaining string push-sites to this at-source form is ongoing.