# 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.
If you want a symptom-first entrypoint, start with [Common Error Recipes](recipes_common_errors.md) and then return here for details.

---

## 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:

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

Fix:
- Run:

 ```bash
 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:

```text
[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 `--no-exclude-backbone`.

---

## 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:

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

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

 ```bash
 pdb2reaction -i R.pdb P.pdb -c 'SAM,GPP' -l '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:

 ```bash
 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:

 ```bash
 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`:

 ```bash
 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:

 ```bash
 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 grad` (Dimer) or `--opt-mode hess` (RS-I-RFO).
- Enable flattening of extra imaginary modes: `--flatten`.
- Increase max cycles: `--max-cycles 20000` (for standalone `tsopt`; `--tsopt-max-cycles 20000` for `all`).
- 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`.
- 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 grad`).
- **Analytical Hessian is slow or causes OOM**: keep the default `FiniteDifference` mode. Only use `--hessian-calc-mode Analytical` if you have ample VRAM (16 GB+ recommended for 500+ atom systems).
- **Workers > 1**: improves UMA throughput on HPC, but disables the analytical Hessian evaluation.
- **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
