Common Error Recipes

Use this page when you know the symptom but do not know which subcommand page to open first. For full details, keep Troubleshooting open in parallel.

Quick routing

Symptom	Start here	Then read
Input & extraction
Missing element columns / extraction aborts	add-elem-info on the original PDB	Input / extraction
[multi] Atom count mismatch / Coordinate shape mismatch / Element sequence mismatch	Regenerate all PDBs with the same prep tool + settings; re-run mm-parm from the current PDB; never reorder atoms after mm-parm	Input / extraction
Charge & spin
ML-region charge is unresolved errors	Set -q/--charge or -l/--ligand-charge explicitly	Charge / spin
Energies/states look wrong after a run	Re-check charge/multiplicity policy in CLI conventions	Charge / spin
Installation & environment
UMA model 401/403 / gated-repo error (huggingface_hub.errors.GatedRepoError)	hf auth login and accept the model license	Installation / environment
ImportError: orb-models is required (or similar for AIMNet2 / MACE)	pip install "mlmm-toolkit[orb]" / "[aimnet]"; MACE installs into a separate env	Installation / environment
mm-parm cannot run (tleap/antechamber/parmchk2 missing)	Fix AmberTools availability first	AmberTools / mm-parm
hessian_ff import/build errors	Rebuild native extension (hessian_ff/native)	hessian_ff build
DMF mode import errors (ase / cyipopt / pydmf)	Install ase + cyipopt (conda-forge) and pydmf>=1.2 (PyPI)	DMF mode
GPU & CUDA
CUDA out-of-memory at runtime (torch.cuda.OutOfMemoryError)	Shrink ML region (--radius), use --hessian-calc-mode FiniteDifference, or move to a larger GPU	CUDA OOM
CUDA/GPU runtime mismatch	Verify torch.cuda.is_available() and CUDA build pairing	CUDA / PyTorch
Convergence
TSOPT does not converge	Reduce trust_radius (RFO-family TS optimizer) or max_step (Dimer/L-BFGS), increase cycles, and validate the TS	Convergence
IRC does not terminate	Reduce --step-size, increase --max-cycles, and validate the TS	Convergence
Optimizer stalls at flat energy (MLIP noise floor)	Let --max-cycles bound the run, or opt in to --stop-plateau	Plateau fallback
Optimizer stalls at flat energy (MLIP noise floor)	Tune --stop-plateau-thresh / --stop-plateau-window if the trigger fires too early or too late	Plateau fallback
Plotting
Plot export failures	Install Chrome runtime for Plotly export	Plot export

Recipe 1: Extraction fails before MEP starts

Signal:

• Errors mention missing element symbols, atom-count mismatch, or empty pockets.

First checks:

• Confirm all inputs are prepared with the same workflow and atom ordering is consistent.

• Ensure element columns are present before running extract or all.

Typical fix path:

• Repair elements -> rerun extraction -> confirm pocket size and residue inclusion.

Recipe 2: Charge/spin validation fails

Signal:

• If the log shows unexpected charges (e.g., protein charge is wrong, or total charge does not match expectations), review the charge resolution rules.

First checks:

• Ensure total charge and multiplicity are physically correct for the target state.

• If using residue maps, validate each residue key in --ligand-charge.

• Verify the resolution rules in CLI Conventions when results look physically inconsistent.

Typical fix path:

• Prefer explicit -q and -m for critical runs, then retry scan/path/tsopt.

Recipe 3: Build or environment blockers

Signal:

• mm-parm tooling not found, hessian_ff import failures, CUDA mismatch.

First checks:

• Confirm required executables and Python extension modules exist in the active env.

• Validate GPU visibility and PyTorch CUDA compatibility.

Typical fix path:

• Repair toolchain/build first, then rerun with --help-advanced to verify available options before full execution.

Recipe 4: Convergence and post-processing failures

Signal:

• TSOPT stalls or IRC branches look unstable.

First checks:

• First-order-saddle certification requires exactly one imaginary mode; inspect its displacement and IRC connectivity.

• TSOPT: reduce trust_radius / max_step and increase its cycle limit. trust_max defaults to 0.10 bohr for RFO-family TS optimizers.

• IRC: reduce --step-size and increase --max-cycles.

• Check whether the configured energy-plateau window is flat while force/step criteria remain unmet. The default fallback stops with status: stalled; it does not declare convergence (see Troubleshooting).

Typical fix path:

• Run a smaller diagnostic case, tune thresholds/step sizes, then scale back up.