Bayesian Optimization troubleshooting

Common issues and fixes

The tool fits your model with PyMC and samples the posterior by MCMC, variational inference, or pathfinder. Most issues trace back to convergence, data formatting, or a mismatch between the model type and your data's shape.

Divergences reported

• A nonzero divergences count in the diagnostics means the sampler couldn't reliably explore part of the posterior geometry.
• Raise target_accept (try 0.95, then 0.99) and increase num_tune.
• Persistent divergences after that usually mean the model needs reparameterizing (for example, a hierarchical model with a funnel-shaped posterior) rather than more tuning.

High R-hat / non-convergence

• r_hat_max well above 1.01 means the chains disagree and the posterior summary isn't trustworthy yet.
• Increase num_samples and num_tune.
• Increase num_chains so the R-hat comparison itself is more informative.
• Check that predictor_columns don't contain near-duplicate or highly collinear columns, which can produce a poorly identified posterior.

Low effective sample size (ESS)

• ess_min far below num_samples * num_chains means the chains are autocorrelated; the posterior is effectively based on fewer independent draws than it looks.
• Increase num_samples, or switch likelihood/link_function if the current combination is a poor match for your outcome's distribution.

Data formatting errors

• data_url must resolve to a readable CSV or Parquet file.
• outcome_column and every entry in predictor_columns must exist in the file and be numeric — encode categorical predictors before submitting.
• For hierarchical, group_column must be present; for pkpd, time_column, concentration_column, and dose_column must all be present.

PK/PD model fit looks wrong

• Confirm administration matches how the dose was actually given (iv_bolus, iv_infusion, or oral) — the compartmental equations differ by route.
• Confirm pk_model (one/two/three compartment) matches the shape of your concentration-time curve; an under-specified model (e.g. one-compartment for clearly biphasic data) will show poor PPC overlap and often more divergences.
• For a population fit, verify subject_column uniquely identifies each individual, and that random_effects names real, present parameters for the chosen pk_model.

Slow jobs

• MCMC (inference_method: "mcmc") is the most reliable but the slowest of the three inference methods; for a faster first look, try pathfinder or variational, understanding both trade some posterior accuracy for speed.
• Large num_chains × num_samples combinations extend runtime roughly linearly; start at the defaults and raise them only if diagnostics call for it.
• Jobs run without a GPU; estimated duration is 2–30 minutes depending on model complexity and data size.

LOO/WAIC missing or NaN

• Confirm compute_loo/compute_waic are enabled (both default true).
• A NaN or warning on LOO usually means some observations have very high Pareto-k diagnostics internally — this points to influential outliers or a poorly specified likelihood, not a bug to retry around.

Still stuck?

• Share the job ID, model_type, and the diagnostics block (divergences, r_hat_max, ess_min).
• Note the sampler settings used (inference_method, num_chains, num_samples, num_tune, target_accept).
• For a PK/PD job, include pk_model, administration, and whether population_model was set.

Read next