Troubleshooting

This page collects common failure modes and practical fixes. It is written to be copy-and-paste friendly: search this page for the error message you see.

Preflight checklist

Before a long run, verify:

  • You can run pdb2reaction -h and see the CLI help.

  • UMA can be downloaded (Hugging Face login/token is available on the machine).

  • For enzyme workflows: your input PDB(s) contain hydrogens and element symbols.

  • When you provide multiple PDBs: they have the same atoms in the same order (only coordinates differ).

Input / extraction problems

“Element symbols are missing … please run add-elem-info”

Typical message:

Element symbols are missing in '...'.
Please run `pdb2reaction add-elem-info -i ...` to populate element columns before running extract.

Fix:

  • Run:

    pdb2reaction add-elem-info -i input.pdb -o input_with_elem.pdb

  • Then re-run extract / all using the updated PDB.

Why it happens:

  • Many PDBs do not populate the element column consistently. extract requires element symbols for reliable atom typing.

“[multi] Atom count mismatch …” or “[multi] Atom order mismatch …”

Typical messages:

[multi] Atom count mismatch between input #1 and input #2: ...
[multi] Atom order mismatch between input #1 and input #2.

Fix:

  • Regenerate all structures with the same preparation workflow (same protonation tool, same settings).

  • If you add hydrogens, do it in a way that produces consistent ordering across all frames.

Tip:

  • For ensembles generated by MD, prefer extracting frames from the same trajectory/topology rather than mixing PDBs produced by different tools.

“My pocket is empty / missing important residues”

Symptoms:

  • The extracted pocket is unexpectedly small.

  • Key catalytic residues are missing.

Fixes to try:

  • Increase --radius (e.g., 2.6 → 3.5 Å).

  • Use --selected-resn to force-include residues (e.g., --selected-resn 'A:123,B:456').

  • If backbone trimming is too aggressive, set --exclude-backbone False.

Charge / spin problems

“Charge is required …” (non-GJF inputs)

Many stages need a total charge when the input is not .gjf. If you omit -q/--charge, the workflow may attempt to derive charge from --ligand-charge (PDB-only) or from a .gjf template.

Fix:

  • Provide charge and multiplicity explicitly:

    pdb2reaction path-search -i R.pdb P.pdb -q 0 -m 1

  • Or (when using extraction) provide a residue-name mapping:

    pdb2reaction -i R.pdb P.pdb -c 'SAM,GPP' --ligand-charge 'SAM:1,GPP:-3'

Installation / environment problems

UMA download/authentication errors

Symptoms:

  • Errors about missing Hugging Face authentication or being unable to download model weights.

Fix:

  • Log in once per environment/machine:

    huggingface-cli login

  • On HPC, ensure your home directory (or HF cache directory) is writable from compute nodes.

CUDA / PyTorch mismatch

Symptoms:

  • torch.cuda.is_available() is false even though you have a GPU.

  • CUDA runtime errors at import time.

Fixes:

  • Install a PyTorch build matching your cluster CUDA runtime.

  • Confirm GPU visibility:

    nvidia-smi
python -c "import torch; print(torch.version.cuda, torch.cuda.is_available())"

DMF mode fails (cyipopt missing)

If you use DMF (--mep-mode dmf) and see errors importing IPOPT/cyipopt:

Fix:

  • Install cyipopt from conda-forge (recommended) before installing pdb2reaction:

    conda install -c conda-forge cyipopt

Plot export fails (Chrome missing)

If figure export fails and you see Plotly/Chrome-related errors:

Fix:

  • Install a headless Chrome once:

    plotly_get_chrome -y

Calculation / convergence problems

TS optimization fails to converge

Symptoms:

  • TS optimization runs for many cycles without converging.

  • Multiple imaginary frequencies remain after optimization.

Fixes to try:

  • Switch optimizer modes: --opt-mode light (Dimer) or --opt-mode heavy (RS-I-RFO).

  • Enable flattening of extra imaginary modes: --flatten-imag-mode True.

  • Increase max cycles: --tsopt-max-cycles 20000.

  • Use tighter convergence: --thresh baker or --thresh gau_tight.

IRC does not terminate properly

Symptoms:

  • IRC stops before reaching a clear minimum.

  • Energy oscillates or gradient remains high.

Fixes to try:

  • Reduce step size: --step-size 0.05 (default is 0.10).

  • Increase max cycles: --max-cycles 200.

  • Check if the TS candidate has only one imaginary frequency before running IRC.

MEP search (GSM/DMF) fails or gives unexpected results

Symptoms:

  • Path search terminates with no valid MEP.

  • Bond changes are not detected correctly.

Fixes to try:

  • Increase --max-nodes (e.g., 15 or 20) for complex reactions.

  • Enable endpoint pre-optimization: --preopt True.

  • Try the alternative MEP method: --mep-mode dmf (if GSM fails) or vice versa.

  • Adjust bond detection parameters in YAML (bond.bond_factor, bond.delta_fraction).

Performance / stability tips

  • Out of memory (VRAM): reduce pocket size (--radius), reduce nodes (--max-nodes), or use lighter optimizer settings (--opt-mode light).

  • Analytical Hessian is slow or OOM: keep the default FiniteDifference Hessian. Only use --hessian-calc-mode Analytical if you have ample VRAM (16 GB+ recommended for 500+ atoms).

  • Workers > 1: improves UMA throughput on HPC, but disables analytical Hessians.

  • Large systems (1000+ atoms): consider extracting a smaller pocket (--radius 2.5) or running on multi-GPU setups.

How to report an issue

When asking for help, include:

  • The exact command line you ran

  • summary.log (or console output)

  • The smallest input files that reproduce the problem (if possible)

  • Your environment: OS, Python, CUDA, PyTorch versions