---
title: Bayesian Optimization troubleshooting
description: 'Clear divergences by raising target_accept, read an r_hat_max above 1.01 or a low ess_min, and fix a PK fit whose pk_model or administration is wrong.'
tags:
  - bayesian
  - 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